Struct RealmProxy

pub struct RealmProxy { /* private fields */ }

Implementations

impl RealmProxy

pub fn new(channel: AsyncChannel) -> Self

Create a new Proxy for fuchsia.component.test/Realm.

pub fn take_event_stream(&self) -> RealmEventStream

Get a Stream of events from the remote end of the protocol.

Panics

Panics if the event stream was already taken.

pub fn add_child( &self, name: &str, url: &str, options: &ChildOptions, ) -> QueryResponseFut<RealmAddChildResult, DefaultFuchsiaResourceDialect>

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.

pub fn add_child_from_decl( &self, name: &str, decl: &Component, options: &ChildOptions, ) -> QueryResponseFut<RealmAddChildFromDeclResult, DefaultFuchsiaResourceDialect>

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.

pub fn add_local_child( &self, name: &str, options: &ChildOptions, ) -> QueryResponseFut<RealmAddLocalChildResult, DefaultFuchsiaResourceDialect>

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.

pub fn add_child_realm( &self, name: &str, options: &ChildOptions, child_realm: ServerEnd<RealmMarker>, ) -> QueryResponseFut<RealmAddChildRealmResult, DefaultFuchsiaResourceDialect>

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.

pub fn get_component_decl( &self, name: &str, ) -> QueryResponseFut<RealmGetComponentDeclResult, DefaultFuchsiaResourceDialect>

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.

pub fn replace_component_decl( &self, name: &str, component_decl: &Component, ) -> QueryResponseFut<RealmReplaceComponentDeclResult, DefaultFuchsiaResourceDialect>

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.

pub fn get_realm_decl( &self, ) -> QueryResponseFut<RealmGetRealmDeclResult, DefaultFuchsiaResourceDialect>

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.

pub fn replace_realm_decl( &self, component_decl: &Component, ) -> QueryResponseFut<RealmReplaceRealmDeclResult, DefaultFuchsiaResourceDialect>

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.

pub fn add_route( &self, capabilities: &[Capability], from: &Ref, to: &[Ref], ) -> QueryResponseFut<RealmAddRouteResult, DefaultFuchsiaResourceDialect>

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.

pub fn read_only_directory( &self, name: &str, to: &[Ref], directory_contents: DirectoryContents, ) -> QueryResponseFut<RealmReadOnlyDirectoryResult, DefaultFuchsiaResourceDialect>

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.

pub fn init_mutable_config_from_package( &self, name: &str, ) -> QueryResponseFut<RealmInitMutableConfigFromPackageResult, DefaultFuchsiaResourceDialect>

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

Allows calling SetConfigValue to override packaged configuration.

pub fn init_mutable_config_to_empty( &self, name: &str, ) -> QueryResponseFut<RealmInitMutableConfigToEmptyResult, DefaultFuchsiaResourceDialect>

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

Allows calling SetConfigValue to provide configuration.

pub fn add_capability( &self, capability: &Capability, ) -> QueryResponseFut<RealmAddCapabilityResult, DefaultFuchsiaResourceDialect>

Add a capability to the realm.

pub fn add_collection( &self, collection: &Collection, ) -> QueryResponseFut<RealmAddCollectionResult, DefaultFuchsiaResourceDialect>

Adds a collection to the realm.

pub fn add_environment( &self, environment: &Environment, ) -> QueryResponseFut<RealmAddEnvironmentResult, DefaultFuchsiaResourceDialect>

Adds an environment to the realm.

pub fn set_config_value( &self, name: &str, key: &str, value: &ConfigValueSpec, ) -> QueryResponseFut<RealmSetConfigValueResult, DefaultFuchsiaResourceDialect>

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:

• NO_CONFIG_SCHEMA: component does not have a config schema
• NO_SUCH_CONFIG_FIELD: key could not be found in component’s config schema
• CONFIG_VALUE_INVALID: value does not meet config schema constraints

Trait Implementations

impl Clone for RealmProxy

fn clone(&self) -> RealmProxy

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RealmProxy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Proxy for RealmProxy

type Protocol = RealmMarker

The protocol which this Proxy controls.

fn from_channel(inner: AsyncChannel) -> Self

Create a proxy over the given channel.

fn into_channel(self) -> Result<AsyncChannel, Self>

Attempt to convert the proxy back into a channel.

fn as_channel(&self) -> &AsyncChannel

Get a reference to the proxy’s underlying channel.

fn into_client_end(self) -> Result<ClientEnd<Self::Protocol>, Self>

Attempt to convert the proxy back into a client end.

fn is_closed(&self) -> bool

Returns true if the proxy has received the PEER_CLOSED signal.

fn on_closed(&self) -> OnSignals<'_, Unowned<'_, Handle>>

Returns a future that completes when the proxy receives the PEER_CLOSED signal.

impl RealmProxyInterface for RealmProxy

type AddChildResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type AddChildFromDeclResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type AddLocalChildResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type AddChildRealmResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type GetComponentDeclResponseFut = QueryResponseFut<Result<Component, RealmBuilderError>>

type ReplaceComponentDeclResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type GetRealmDeclResponseFut = QueryResponseFut<Result<Component, RealmBuilderError>>

type ReplaceRealmDeclResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type AddRouteResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type ReadOnlyDirectoryResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type InitMutableConfigFromPackageResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type InitMutableConfigToEmptyResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type AddCapabilityResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type AddCollectionResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type AddEnvironmentResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

type SetConfigValueResponseFut = QueryResponseFut<Result<(), RealmBuilderError>>

fn add_child( &self, name: &str, url: &str, options: &ChildOptions, ) -> Self::AddChildResponseFut

fn add_child_from_decl( &self, name: &str, decl: &Component, options: &ChildOptions, ) -> Self::AddChildFromDeclResponseFut

fn add_local_child( &self, name: &str, options: &ChildOptions, ) -> Self::AddLocalChildResponseFut

fn add_child_realm( &self, name: &str, options: &ChildOptions, child_realm: ServerEnd<RealmMarker>, ) -> Self::AddChildRealmResponseFut

fn get_component_decl(&self, name: &str) -> Self::GetComponentDeclResponseFut

fn replace_component_decl( &self, name: &str, component_decl: &Component, ) -> Self::ReplaceComponentDeclResponseFut

fn get_realm_decl(&self) -> Self::GetRealmDeclResponseFut

fn replace_realm_decl( &self, component_decl: &Component, ) -> Self::ReplaceRealmDeclResponseFut

fn add_route( &self, capabilities: &[Capability], from: &Ref, to: &[Ref], ) -> Self::AddRouteResponseFut

fn read_only_directory( &self, name: &str, to: &[Ref], directory_contents: DirectoryContents, ) -> Self::ReadOnlyDirectoryResponseFut

fn init_mutable_config_from_package( &self, name: &str, ) -> Self::InitMutableConfigFromPackageResponseFut

fn init_mutable_config_to_empty( &self, name: &str, ) -> Self::InitMutableConfigToEmptyResponseFut

fn add_capability( &self, capability: &Capability, ) -> Self::AddCapabilityResponseFut

fn add_collection( &self, collection: &Collection, ) -> Self::AddCollectionResponseFut

fn add_environment( &self, environment: &Environment, ) -> Self::AddEnvironmentResponseFut

fn set_config_value( &self, name: &str, key: &str, value: &ConfigValueSpec, ) -> Self::SetConfigValueResponseFut