Struct RealmSynchronousProxy

Source

pub struct RealmSynchronousProxy { /* private fields */ }

Implementations§

Source §

pub fn wait_for_event( &self, deadline: MonotonicInstant, ) -> Result<RealmEvent, Error>

Waits until an event arrives and returns it. It is safe for other threads to make concurrent requests while waiting for an event.

Source

pub fn add_child( &self, name: &str, url: &str, options: &ChildOptions, ___deadline: MonotonicInstant, ) -> Result<RealmAddChildResult, Error>

Adds a component to the realm.

The url can be in one of the following formats:

an absolute component URL (such as, “fuchsia-pkg://fuchsia.com/some-package#meta/some-component.cm”)
a relative path component URL to a subpackaged component (like, “some-subpackage#meta/subpackaged-component.cm”); or
a relative fragment-only URL (like, #meta/other-component.cm; see https://fuchsia.dev/fuchsia-src/reference/components/url#relative-fragment-only) indicating the path to a component manifest in the pkg_dir supplied to RealmBuilderFactory::Create*().

The realm builder client typically passes a handle to its own /pkg directory, and bundles the other-component into the same package.

Of the three URL types, only component declarations added via the fragment-only URL can be modified, via GetComponentDecl/ReplaceComponentDecl because realm builder actually performs its own component resolution from the component’s manifest and files bundled in the provided pkg_dir (typically from the package shared by the realm builder client component and the components added via fragment-only URL).

Errors:

CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.
INVALID_MANIFEST_EXTENSION: url does not end with .cm
DECL_NOT_FOUND: The test package does not contain the component declaration referenced by a fragment-only component URL.
DECL_READ_ERROR: Encountered an I/O error when attempting to read a component declaration referenced by a fragment-only component URL from the test package.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn add_child_from_decl( &self, name: &str, decl: &Component, options: &ChildOptions, ___deadline: MonotonicInstant, ) -> Result<RealmAddChildFromDeclResult, Error>

Adds a component to this realm whose declaration is set to decl. When launched, the component will share the test package as its package directory, and may access any resources from it.

Errors:

CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.
INVALID_COMPONENT_DECL: decl failed validation.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn add_local_child( &self, name: &str, options: &ChildOptions, ___deadline: MonotonicInstant, ) -> Result<RealmAddLocalChildResult, Error>

Adds a component to the realm whose implementation will be provided by the client. When this component should be started, the runner channel passed into Build will receive a start request for a component whose ProgramDecl contains the moniker from the root of the constructed realm for the child that is to be run under the program key LOCAL_COMPONENT_NAME.

Errors:

CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn add_child_realm( &self, name: &str, options: &ChildOptions, child_realm: ServerEnd<RealmMarker>, ___deadline: MonotonicInstant, ) -> Result<RealmAddChildRealmResult, Error>

Adds a child realm which can be built with the client end of child_realm.

Errors:

CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn add_child_realm_from_relative_url( &self, name: &str, relative_url: &str, options: &ChildOptions, child_realm: ServerEnd<RealmMarker>, ___deadline: MonotonicInstant, ) -> Result<RealmAddChildRealmFromRelativeUrlResult, Error>

Adds a child realm which can be built with the client end of child_realm, and whose contents are initialized from relative_url. relative_url must be a fragment-only URL.

Source

pub fn add_child_realm_from_decl( &self, name: &str, decl: &Component, options: &ChildOptions, child_realm: ServerEnd<RealmMarker>, ___deadline: MonotonicInstant, ) -> Result<RealmAddChildRealmFromDeclResult, Error>

Adds a child realm which can be built with the client end of child_realm, and whose contents are initialized from decl.

Source

pub fn get_component_decl( &self, name: &str, ___deadline: MonotonicInstant, ) -> Result<RealmGetComponentDeclResult, Error>

Returns the component decl for the given component. name must refer to a component that is one of the following:

A component with a local implementation
A legacy component
A component added with a fragment-only URL (typically, components bundled in the same package as the realm builder client, sharing the same /pkg directory, for example, #meta/other-component.cm; see https://fuchsia.dev/fuchsia-src/reference/components/url#relative-fragment-only)
An automatically generated realm (ex: the root)

Errors:

NO_SUCH_CHILD: This realm does not contain a child with the given name.
CHILD_DECL_NOT_VISIBLE: The component decl cannot be fetched for the referenced child, because the child was added to the realm using a modern (not legacy) absolute URL or subpackaged component’s relative path URL.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn replace_component_decl( &self, name: &str, component_decl: &Component, ___deadline: MonotonicInstant, ) -> Result<RealmReplaceComponentDeclResult, Error>

Replaces the component decl for the given component. name must refer to a component that is one of the following:

A component with a local implementation
A legacy component
A component added with a fragment-only URL (typically, components bundled in the same package as the realm builder client, sharing the same /pkg directory, for example, #meta/other-component.cm; see https://fuchsia.dev/fuchsia-src/reference/components/url#relative-fragment-only)
An automatically generated realm (ex: the root)

Errors:

NO_SUCH_CHILD: This realm does not contain a child with the given name.
CHILD_ALREADY_EXISTS: The component whose decl is being replaced has had a child added to it through realm builder with the same name as an element in component_decl.children.
CHILD_DECL_NOT_VISIBLE: The component decl cannot be manipulated for the referenced child, because the child was added to the realm using an absolute (not relative) and modern (not legacy) URL.
INVALID_COMPONENT_DECL: component_decl failed validation.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn get_realm_decl( &self, ___deadline: MonotonicInstant, ) -> Result<RealmGetRealmDeclResult, Error>

Returns the component decl for this realm.

Errors:

BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn replace_realm_decl( &self, component_decl: &Component, ___deadline: MonotonicInstant, ) -> Result<RealmReplaceRealmDeclResult, Error>

Replaces the component decl for this realm.

Errors:

INVALID_COMPONENT_DECL: component_decl failed validation.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn use_nested_component_manager( &self, component_manager_relative_url: &str, ___deadline: MonotonicInstant, ) -> Result<RealmUseNestedComponentManagerResult, Error>

Inform the realm builder server that this realm is using a nested component manager. It’s expected that the client library has already replaced the realm’s declaration with a passthrough component manager declaration, with the exception of the root url. This method will arrange for [Builder.Build] to install the realm’s generated url as the root url in this component manager.

Source

pub fn add_route( &self, capabilities: &[Capability], from: &Ref, to: &[Ref], ___deadline: MonotonicInstant, ) -> Result<RealmAddRouteResult, Error>

Identical to AddRouteFromDictionary, except it does not accept from_dictionary which it always sets to “.”.

Source

pub fn add_route_from_dictionary( &self, capabilities: &[Capability], from: &Ref, from_dictionary: &str, to: &[Ref], ___deadline: MonotonicInstant, ) -> Result<RealmAddRouteFromDictionaryResult, Error>

Mutates component manifests in the realm such that every component in to will have a valid capability route for each item in capabilities provided by from.

Errors:

NO_SUCH_SOURCE: from references a non-existent child.
NO_SUCH_TARGET: to references a non-existent child.
CAPABILITIES_EMPTY: capabilities is empty.
TARGETS_EMPTY: to is empty.
SOURCE_AND_TARGET_MATCH: from is equal to one of the elements in to.
INVALID_COMPONENT_DECL: The requested route caused one of the involved manifests to fail validation.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn read_only_directory( &self, name: &str, to: &[Ref], directory_contents: DirectoryContents, ___deadline: MonotonicInstant, ) -> Result<RealmReadOnlyDirectoryResult, Error>

Offers a directory capability to a component in this realm. The directory will be read-only (i.e. have r* rights), and will have the contents described in directory_contents.

Errors:

NO_SUCH_TARGET: offer-to references a non-existent child.
BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Source

pub fn add_storage( &self, name: &str, to: &[Ref], storage_admin: Option<ServerEnd<StorageAdminMarker>>, ___deadline: MonotonicInstant, ) -> Result<RealmAddStorageResult, Error>

Creates and routes a new storage capability to the provided targets. Optionally can connect the provided channel the the fuchsia.sys2.StorageAdmin protocol for this storage capability.

Source

pub fn init_mutable_config_from_package( &self, name: &str, ___deadline: MonotonicInstant, ) -> Result<RealmInitMutableConfigFromPackageResult, Error>

Load any packaged configuration for name before using values provided to the builder.

Allows calling SetConfigValue to override packaged configuration.

Source

pub fn init_mutable_config_to_empty( &self, name: &str, ___deadline: MonotonicInstant, ) -> Result<RealmInitMutableConfigToEmptyResult, Error>

Use only values provided to the builder for name’s configuration.

Allows calling SetConfigValue to provide configuration.

Source

pub fn add_capability( &self, capability: &Capability, ___deadline: MonotonicInstant, ) -> Result<RealmAddCapabilityResult, Error>

Add a capability to the realm.

Source

pub fn add_collection( &self, collection: &Collection, ___deadline: MonotonicInstant, ) -> Result<RealmAddCollectionResult, Error>

Adds a collection to the realm.

Source

pub fn add_environment( &self, environment: &Environment, ___deadline: MonotonicInstant, ) -> Result<RealmAddEnvironmentResult, Error>

Adds an environment to the realm.

Source

pub fn set_config_value( &self, name: &str, key: &str, value: &ConfigValueSpec, ___deadline: MonotonicInstant, ) -> Result<RealmSetConfigValueResult, Error>

Sets the configuration value for a field specified by key. The component specified must have a config schema with this field. The value must conform to all constraints as defined by the schema.

This method must be called after either InitMutableConfigFromPackage or InitMutableConfigToEmpty.

Errors: