Enum RealmRequest

pub enum RealmRequest {
    AddChild {
        name: String,
        url: String,
        options: ChildOptions,
        responder: RealmAddChildResponder,
    },
    AddChildFromDecl {
        name: String,
        decl: Component,
        options: ChildOptions,
        responder: RealmAddChildFromDeclResponder,
    },
    AddLocalChild {
        name: String,
        options: ChildOptions,
        responder: RealmAddLocalChildResponder,
    },
    AddChildRealm {
        name: String,
        options: ChildOptions,
        child_realm: ServerEnd<RealmMarker>,
        responder: RealmAddChildRealmResponder,
    },
    AddChildRealmFromRelativeUrl {
        name: String,
        relative_url: String,
        options: ChildOptions,
        child_realm: ServerEnd<RealmMarker>,
        responder: RealmAddChildRealmFromRelativeUrlResponder,
    },
    AddChildRealmFromDecl {
        name: String,
        decl: Component,
        options: ChildOptions,
        child_realm: ServerEnd<RealmMarker>,
        responder: RealmAddChildRealmFromDeclResponder,
    },
    GetComponentDecl {
        name: String,
        responder: RealmGetComponentDeclResponder,
    },
    ReplaceComponentDecl {
        name: String,
        component_decl: Component,
        responder: RealmReplaceComponentDeclResponder,
    },
    GetRealmDecl {
        responder: RealmGetRealmDeclResponder,
    },
    ReplaceRealmDecl {
        component_decl: Component,
        responder: RealmReplaceRealmDeclResponder,
    },
    UseNestedComponentManager {
        component_manager_relative_url: String,
        responder: RealmUseNestedComponentManagerResponder,
    },
    AddRoute {
        capabilities: Vec<Capability>,
        from: Ref,
        to: Vec<Ref>,
        responder: RealmAddRouteResponder,
    },
    ReadOnlyDirectory {
        name: String,
        to: Vec<Ref>,
        directory_contents: DirectoryContents,
        responder: RealmReadOnlyDirectoryResponder,
    },
    InitMutableConfigFromPackage {
        name: String,
        responder: RealmInitMutableConfigFromPackageResponder,
    },
    InitMutableConfigToEmpty {
        name: String,
        responder: RealmInitMutableConfigToEmptyResponder,
    },
    AddCapability {
        capability: Capability,
        responder: RealmAddCapabilityResponder,
    },
    AddCollection {
        collection: Collection,
        responder: RealmAddCollectionResponder,
    },
    AddEnvironment {
        environment: Environment,
        responder: RealmAddEnvironmentResponder,
    },
    SetConfigValue {
        name: String,
        key: String,
        value: ConfigValueSpec,
        responder: RealmSetConfigValueResponder,
    },
}

Variants

AddChild

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.

Fields

name: String

url: String

options: ChildOptions

responder: RealmAddChildResponder

AddChildFromDecl

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.

Fields

name: String

decl: Component

options: ChildOptions

responder: RealmAddChildFromDeclResponder

AddLocalChild

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.

Fields

name: String

options: ChildOptions

responder: RealmAddLocalChildResponder

AddChildRealm

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.

Fields

name: String

options: ChildOptions

child_realm: ServerEnd<RealmMarker>

responder: RealmAddChildRealmResponder

AddChildRealmFromRelativeUrl

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.

Fields

name: String

relative_url: String

options: ChildOptions

child_realm: ServerEnd<RealmMarker>

responder: RealmAddChildRealmFromRelativeUrlResponder

AddChildRealmFromDecl

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

Fields

name: String

decl: Component

options: ChildOptions

child_realm: ServerEnd<RealmMarker>

responder: RealmAddChildRealmFromDeclResponder

GetComponentDecl

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.

Fields

name: String

responder: RealmGetComponentDeclResponder

ReplaceComponentDecl

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.

Fields

name: String

component_decl: Component

responder: RealmReplaceComponentDeclResponder

GetRealmDecl

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.

Fields

responder: RealmGetRealmDeclResponder

ReplaceRealmDecl

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.

Fields

component_decl: Component

responder: RealmReplaceRealmDeclResponder

UseNestedComponentManager

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.

Fields

component_manager_relative_url: String

responder: RealmUseNestedComponentManagerResponder

AddRoute

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.

Fields

capabilities: Vec<Capability>

from: Ref

to: Vec<Ref>

responder: RealmAddRouteResponder

ReadOnlyDirectory

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.

Fields

name: String

to: Vec<Ref>

directory_contents: DirectoryContents

responder: RealmReadOnlyDirectoryResponder

InitMutableConfigFromPackage

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

Allows calling SetConfigValue to override packaged configuration.

Fields

name: String

responder: RealmInitMutableConfigFromPackageResponder

InitMutableConfigToEmpty

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

Allows calling SetConfigValue to provide configuration.

Fields

name: String

responder: RealmInitMutableConfigToEmptyResponder

AddCapability

Add a capability to the realm.

Fields

capability: Capability

responder: RealmAddCapabilityResponder

AddCollection

Adds a collection to the realm.

Fields

collection: Collection

responder: RealmAddCollectionResponder

AddEnvironment

Adds an environment to the realm.

Fields

environment: Environment

responder: RealmAddEnvironmentResponder

SetConfigValue

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

Fields

name: String

key: String

value: ConfigValueSpec

responder: RealmSetConfigValueResponder

Implementations

impl RealmRequest

pub fn into_add_child( self, ) -> Option<(String, String, ChildOptions, RealmAddChildResponder)>

pub fn into_add_child_from_decl( self, ) -> Option<(String, Component, ChildOptions, RealmAddChildFromDeclResponder)>

pub fn into_add_local_child( self, ) -> Option<(String, ChildOptions, RealmAddLocalChildResponder)>

pub fn into_add_child_realm( self, ) -> Option<(String, ChildOptions, ServerEnd<RealmMarker>, RealmAddChildRealmResponder)>

pub fn into_add_child_realm_from_relative_url( self, ) -> Option<(String, String, ChildOptions, ServerEnd<RealmMarker>, RealmAddChildRealmFromRelativeUrlResponder)>

pub fn into_add_child_realm_from_decl( self, ) -> Option<(String, Component, ChildOptions, ServerEnd<RealmMarker>, RealmAddChildRealmFromDeclResponder)>

pub fn into_get_component_decl( self, ) -> Option<(String, RealmGetComponentDeclResponder)>

pub fn into_replace_component_decl( self, ) -> Option<(String, Component, RealmReplaceComponentDeclResponder)>

pub fn into_get_realm_decl(self) -> Option<RealmGetRealmDeclResponder>

pub fn into_replace_realm_decl( self, ) -> Option<(Component, RealmReplaceRealmDeclResponder)>

pub fn into_use_nested_component_manager( self, ) -> Option<(String, RealmUseNestedComponentManagerResponder)>

pub fn into_add_route( self, ) -> Option<(Vec<Capability>, Ref, Vec<Ref>, RealmAddRouteResponder)>

pub fn into_read_only_directory( self, ) -> Option<(String, Vec<Ref>, DirectoryContents, RealmReadOnlyDirectoryResponder)>

pub fn into_init_mutable_config_from_package( self, ) -> Option<(String, RealmInitMutableConfigFromPackageResponder)>

pub fn into_init_mutable_config_to_empty( self, ) -> Option<(String, RealmInitMutableConfigToEmptyResponder)>

pub fn into_add_capability( self, ) -> Option<(Capability, RealmAddCapabilityResponder)>

pub fn into_add_collection( self, ) -> Option<(Collection, RealmAddCollectionResponder)>

pub fn into_add_environment( self, ) -> Option<(Environment, RealmAddEnvironmentResponder)>

pub fn into_set_config_value( self, ) -> Option<(String, String, ConfigValueSpec, RealmSetConfigValueResponder)>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for RealmRequest

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

Formats the value using the given formatter.