class Realm

class Realm

Defined at line 11475 of file fidling/gen/sdk/fidl/fuchsia.component.test/fuchsia.component.test/hlcpp/fuchsia/component/test/cpp/fidl.h

Public Members

static const char[] Name_

Public Methods

void ~Realm ()
void AddChild (::std::string name, ::std::string url, ::fuchsia::component::test::ChildOptions options, AddChildCallback callback)

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.

void AddChildFromDecl (::std::string name, ::fuchsia::component::decl::Component decl, ::fuchsia::component::test::ChildOptions options, AddChildFromDeclCallback callback)

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.

void AddLocalChild (::std::string name, ::fuchsia::component::test::ChildOptions options, AddLocalChildCallback callback)

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.

void AddChildRealm (::std::string name, ::fuchsia::component::test::ChildOptions options, ::fidl::InterfaceRequest< ::fuchsia::component::test::Realm> child_realm, AddChildRealmCallback callback)

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.

void AddChildRealmFromRelativeUrl (::std::string name, ::std::string relative_url, ::fuchsia::component::test::ChildOptions options, ::fidl::InterfaceRequest< ::fuchsia::component::test::Realm> child_realm, AddChildRealmFromRelativeUrlCallback callback)

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.

void AddChildRealmFromDecl (::std::string name, ::fuchsia::component::decl::Component decl, ::fuchsia::component::test::ChildOptions options, ::fidl::InterfaceRequest< ::fuchsia::component::test::Realm> child_realm, AddChildRealmFromDeclCallback callback)

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

`child_realm`, and whose contents are initialized from `decl`.

void GetComponentDecl (::std::string name, GetComponentDeclCallback callback)

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.

void ReplaceComponentDecl (::std::string name, ::fuchsia::component::decl::Component component_decl, ReplaceComponentDeclCallback callback)

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.

void GetRealmDecl (GetRealmDeclCallback callback)

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.

void ReplaceRealmDecl (::fuchsia::component::decl::Component component_decl, ReplaceRealmDeclCallback callback)

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.

void UseNestedComponentManager (::std::string component_manager_relative_url, UseNestedComponentManagerCallback callback)

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.

void AddRoute (::std::vector< ::fuchsia::component::test::Capability> capabilities, ::fuchsia::component::decl::Ref from, ::std::vector< ::fuchsia::component::decl::Ref> to, AddRouteCallback callback)

Identical to `AddRouteFromDictionary`, except it does not accept `from_dictionary` which

it always sets to ".".

void AddRouteFromDictionary (::std::vector< ::fuchsia::component::test::Capability> capabilities, ::fuchsia::component::decl::Ref from, ::std::string from_dictionary, ::std::vector< ::fuchsia::component::decl::Ref> to, AddRouteFromDictionaryCallback callback)

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.

void ReadOnlyDirectory (::std::string name, ::std::vector< ::fuchsia::component::decl::Ref> to, ::fuchsia::component::test::DirectoryContents directory_contents, ReadOnlyDirectoryCallback callback)

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.

void AddStorage (::std::string name, ::std::vector< ::fuchsia::component::decl::Ref> to, ::fidl::InterfaceRequest< ::fuchsia::component::StorageAdmin> storage_admin, AddStorageCallback callback)

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.

void InitMutableConfigFromPackage (::std::string name, InitMutableConfigFromPackageCallback callback)

Load any packaged configuration for `name` before using values provided to

the builder.

Allows calling `SetConfigValue` to override packaged configuration.

void InitMutableConfigToEmpty (::std::string name, InitMutableConfigToEmptyCallback callback)

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

Allows calling `SetConfigValue` to provide configuration.

void AddCapability (::fuchsia::component::decl::Capability capability, AddCapabilityCallback callback)

Add a capability to the realm.

void AddCollection (::fuchsia::component::decl::Collection collection, AddCollectionCallback callback)

Adds a collection to the realm.

void AddEnvironment (::fuchsia::component::decl::Environment environment, AddEnvironmentCallback callback)

Adds an environment to the realm.

void SetConfigValue (::std::string name, ::std::string key, ::fuchsia::component::decl::ConfigValueSpec value, SetConfigValueCallback callback)

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