Google is committed to advancing racial equity for Black communities. See how.

fuchsia.realm.builder

PROTOCOLS

FrameworkIntermediary

Defined in fuchsia.realm.builder/realm_builder.fidl

This stateful protocol can be used to construct a new component realm at runtime. This new realm is built iteratively by calling the methods on this protocol to add new components and capability routes between them. Due to the stateful nature of this protocol, one realm may be constructed per connection.

Once the realm details are successfully processed, Commit should be called to produce a URL which can be used to create the component.

Commit

Assembles the realm being constructed and returns the URL for the root component in the realm, which may then be used to create a new component in any collection where fuchsia-test-component is properly set up.

Request

NameType

Response

NameType
result FrameworkIntermediary_Commit_Result

Contains

Returns true if the component exists in this realm.

Request

NameType
moniker string[4096]

Response

NameType
exists bool

GetComponentDecl

Returns the current value of a component decl in the realm being constructed. Note that this cannot retrieve decls through external URLs, so for example if SetComponent is called with Component::url and then GetComponentDecl is called with the same moniker, an error will be returned.

Request

NameType
moniker string[4096]

Response

NameType
result FrameworkIntermediary_GetComponentDecl_Result

Init

Initializes this connection to the framework intermediary. This function should be called at the stat of every new FrameworkIntermediary connection, with the pkg_dir_handle argument providing a connection to the test's package with rx* permissions. Components that are added with a relative URL are loaded from this directory handle. If this call is not made, any call to SetComponent with a relative URL will return an error.

Request

NameType
pkg_dir_handle fuchsia.io/Directory

Response

NameType
result FrameworkIntermediary_Init_Result

MarkAsEager

Marks the component and any ancestors of it as eager, ensuring that the component is started immediately once the realm is bound to.

Request

NameType
moniker string[4096]

Response

NameType
result FrameworkIntermediary_MarkAsEager_Result

NewMockId

Registers a new mock component. When a mock component with the returned ID in its program.mock_id field is run, OnMockRunRequest is called over the same channel that the mock was registered on.

Request

NameType

Response

NameType
mock_id string[1000]

OnMockRunRequest

The component framework is requesting that a mock component start running

Response

NameType
mock_id string[1000]
start_info MockComponentStartInfo

OnMockStopRequest

The component framework is requesting that a mock component stop running

Response

NameType
mock_id string[1000]

RouteCapability

Adds a capability route to the realm being constructed, adding any necessary offers, exposes, uses, and capability declarations to any component involved in the route. Note that components added with Component::url can not be modified, and they are presumed to already have the declarations needed for the route to be valid. If an error is returned some of the components in the route may have been updated while others were not.

Request

NameType
route CapabilityRoute

Response

NameType
result FrameworkIntermediary_RouteCapability_Result

SetComponent

Sets the component to the provided component source. If the source is a Component::decl then a new node is added to the internal tree structure maintained for this connection. If the source is a Component::url then a new ChildDecl is added to the parent of the moniker. If any parents for the component do not exist then they are added. If a different component already exists under this moniker, then it is replaced.

Request

NameType
moniker string[4096]
component Component

Response

NameType
result FrameworkIntermediary_SetComponent_Result

STRUCTS

AboveRoot

Defined in fuchsia.realm.builder/realm_builder.fidl

The capability route's endpoint exists above the constructed realm, and is offered to the realm's collection or will be accessed by the parent using fuchsia.sys2#Realm.

NameTypeDescriptionDefault

FrameworkIntermediary_Commit_Response

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescriptionDefault
root_component_url string[4096] No default

FrameworkIntermediary_GetComponentDecl_Response

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescriptionDefault
component_decl fuchsia.sys2/ComponentDecl No default

FrameworkIntermediary_Init_Response

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescriptionDefault

FrameworkIntermediary_MarkAsEager_Response

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescriptionDefault

FrameworkIntermediary_RouteCapability_Response

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescriptionDefault

FrameworkIntermediary_SetComponent_Response

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescriptionDefault

ENUMS

RealmBuilderError strict

Type: uint32

Defined in fuchsia.realm.builder/realm_builder.fidl

NameValueDescription
NODE_BEHIND_CHILD_DECL 0

An attempt was made to interact with a component declaration for a component which is located behind a child declaration, and is thus not directly available to RealmBuilder.

NO_SUCH_CHILD 1

An attempt was made to retrieve a child of a component which does not exist.

ROOT_CANNOT_BE_SET_TO_URL 2

The root component cannot have a URL-based source.

ROOT_CANNOT_BE_EAGER 3

The root component cannot be marked as eager.

BAD_FIDL 4

RealmBuilder failed to parse the FIDL from one of the arguments.

MISSING_FIELD 5

A required field was missing in the input.

ROUTE_TARGETS_EMPTY 6

The set of targets for a route is not allowed to be empty.

MISSING_ROUTE_SOURCE 7

The source for the route does not exist.

MISSING_ROUTE_TARGET 8

A target for the route does not exist.

ROUTE_SOURCE_AND_TARGET_MATCH 9

A target for the route is equal to the source, and it is impossible to route a component's capability to itself.

VALIDATION_ERROR 10

A component manifest has failed validation.

UNABLE_TO_EXPOSE 11

The requested route is impossible because the capability type cannot be exposed.

STORAGE_SOURCE_INVALID 12

The source of the route is invalid because currently "above root" is the only supported source for storage capabilities.

MONIKER_NOT_FOUND 13

There is no component in this realm with the given moniker.

PKG_DIR_ALREADY_SET 14

The package directory has already been set for this connection.

PKG_DIR_NOT_SET 15

Unable to load component from package, the package dir is not set.

PKG_DIR_IO_ERROR 16

Failed to load component from package due to IO error.

FAILED_TO_LOAD_COMPONENT_DECL 17

Failed to load the component decl.

TABLES

CapabilityRoute

Defined in fuchsia.realm.builder/realm_builder.fidl

A capability route, denoting where a capability comes from and where it goes to.

OrdinalNameTypeDescription
1 capability Capability
2 source RouteEndpoint
3 targets vector<RouteEndpoint>[100]

DirectoryCapability

Defined in fuchsia.realm.builder/realm_builder.fidl

A directory capability

OrdinalNameTypeDescription
1 name string[100]
2 path string[1024]
3 rights fuchsia.io2/Rights

MockComponentStartInfo resource

Defined in fuchsia.realm.builder/realm_builder.fidl

The handles a mock component uses to consume capabilities from and provide capabilities to the framework.

OrdinalNameTypeDescription
1 ns vector<fuchsia.component.runner/ComponentNamespaceEntry>[32]
2 outgoing_dir request<fuchsia.io/Directory>

ProtocolCapability

Defined in fuchsia.realm.builder/realm_builder.fidl

A protocol capability

OrdinalNameTypeDescription
1 name string[100]

StorageCapability

Defined in fuchsia.realm.builder/realm_builder.fidl

A storage capability

OrdinalNameTypeDescription
1 name string[100]
2 path string[1024]

UNIONS

Capability flexible

Defined in fuchsia.realm.builder/realm_builder.fidl

A capability to be routed

NameTypeDescription
protocol ProtocolCapability
directory DirectoryCapability
storage StorageCapability

Component flexible

Defined in fuchsia.realm.builder/realm_builder.fidl

A component to be added to the realm, which is either a component declaration that RealmBuilder should provide or an external URL that should be referenced in a child decl.

NameTypeDescription
decl fuchsia.sys2/ComponentDecl
url string[4096]
legacy_url string[4096]

FrameworkIntermediary_Commit_Result strict

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescription
response FrameworkIntermediary_Commit_Response
err RealmBuilderError

FrameworkIntermediary_GetComponentDecl_Result strict

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescription
response FrameworkIntermediary_GetComponentDecl_Response
err RealmBuilderError

FrameworkIntermediary_Init_Result strict

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescription
response FrameworkIntermediary_Init_Response
err RealmBuilderError

FrameworkIntermediary_MarkAsEager_Result strict

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescription
response FrameworkIntermediary_MarkAsEager_Response
err RealmBuilderError

FrameworkIntermediary_RouteCapability_Result strict

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescription
response FrameworkIntermediary_RouteCapability_Response
err RealmBuilderError

FrameworkIntermediary_SetComponent_Result strict

Defined in fuchsia.realm.builder/realm_builder.fidl

NameTypeDescription
response FrameworkIntermediary_SetComponent_Response
err RealmBuilderError

RouteEndpoint flexible

Defined in fuchsia.realm.builder/realm_builder.fidl

The endpoint of a capability route, describing either the provider or consumer of a capability.

NameTypeDescription
component string[1024]
above_root AboveRoot

CONSTANTS

NameValueTypeDescription
MAX_LEN_ROUTE_ENDPOINTS 100 uint32
MAX_MOCK_ID_LENGTH 1000 uint32