PROTOCOLS
Binder
Defined in fuchsia.component/binder.fidl
A framework-provided protocol that allows components that use it to bind to the component that exposes it. The act of connecting to this protocol will trigger the bind. Thus, this protocol contains no methods. For more details on binding, see https://fuchsia.dev/fuchsia-src/concepts/components/v2/lifecycle#binding.
When a component connects to protocol, the component exposing this capability will be started if it's not already running. Upon a failure to start, the component framework will close the server end of the channel with a zx.status epitaph.
Note: The component doesn't need to serve this protocol, it is implemented by the framework.
ChildIterator
Defined in fuchsia.component/realm.fidl
A protocol to iterate over the list of children in a realm.
Next
Advance the iterator and return the next batch of children.
Returns a vector of ChildRef
. Returns an empty vector when there are
no more children.
Request
<EMPTY>
Response
Name | Type |
---|---|
children |
vector<fuchsia.component.decl/ChildRef>[128]
|
Realm
Defined in fuchsia.component/realm.fidl
A protocol used by a component instance to manage its own realm, such as for binding to its children.
Requests to this protocol are processed in the order they are received. Clients that wish to send requests in parallel should open multiple connections.
The component framework provides this service to components that use
fuchsia.component.Realm
.
CreateChild
Creates a child component instance dynamically. When this function returns successfully, the instance exists, but it may not be running.
The environment of the child instance is determined by the environment
of the collection. decl
must not set environment
.
Errors:
INVALID_ARGUMENTS
:collection
is not a valid reference orchild
is not a valid declaration.COLLECTION_NOT_FOUND
:collection
does not exist.INSTANCE_ALREADY_EXISTS
:decl.name
already exists incollection
.INSTANCE_CANNOT_RESOLVE
:child
's component declaration failed to resolve in aSingleRun
collection.NO_SPACE
: Could not allocate storage for the new instance.INSTANCE_DIED
: This realm no longer exists.
Request
Name | Type |
---|---|
collection |
fuchsia.component.decl/CollectionRef
|
decl |
fuchsia.component.decl/Child
|
args |
CreateChildArgs
|
Response
Name | Type |
---|---|
result |
Realm_CreateChild_Result
|
DestroyChild
Destroys a dynamically-created component instance. When this function returns, the instance is destroyed and has stopped running. However, cleanup of the component's resources (such as its isolated storage) may happen in the background after this function returns.
Errors:
INVALID_ARGUMENTS
:child
is not a valid reference or does not refer to a dynamic instance.INSTANCE_NOT_FOUND
:child
does not exist.COLLECTION_NOT_FOUND
:collection
does not exist.INSTANCE_DIED
: This realm no longer exists.
Request
Name | Type |
---|---|
child |
fuchsia.component.decl/ChildRef
|
Response
Name | Type |
---|---|
result |
Realm_DestroyChild_Result
|
ListChildren
Returns an iterator that lists all instances in a collection.
NOTE: The results are not guaranteed to be consistent. Instances may be created or destroyed while the iterator is live, but those changes won't be observed by the iterator after this method returns.
Errors:
INVALID_ARGUMENTS
:collection
is not a valid reference oriter
does not haveZX_RIGHT_WAIT
.COLLECTION_NOT_FOUND
:collection
does not exist.INSTANCE_DIED
: This realm no longer exists.- If
iter
does not have standard channel rights, this function may returnACCESS_DENIED
or component manager may closeiter
.
Request
Name | Type |
---|---|
collection |
fuchsia.component.decl/CollectionRef
|
iter |
request<ChildIterator>
|
Response
Name | Type |
---|---|
result |
Realm_ListChildren_Result
|
OpenExposedDir
Opens the exposed directory of a child component instance. When this
function successfully returns, exposed_dir
is bound to a directory
that contains the capabilities which the child exposed to its realm
via ComponentDecl.exposes
(specified via "expose" declarations in
the component's manifest). The child component will not start as a
result of this call. Instead, starting will occur iff the parent binds
to one of the capabilities contained within exposed_dir
.
exposed_dir
is open as long as child
exists.
Errors:
INVALID_ARGUMENTS
:child
is not a valid child reference.INSTANCE_NOT_FOUND
:child
does not exist.INSTANCE_CANNOT_RESOLVE
:child
's component declaration failed to resolve.INSTANCE_DIED
: This realm no longer exists.
Request
Name | Type |
---|---|
child |
fuchsia.component.decl/ChildRef
|
exposed_dir |
request<fuchsia.io/Directory>
|
Response
Name | Type |
---|---|
result |
Realm_OpenExposedDir_Result
|
STRUCTS
Realm_CreateChild_Response
Defined in fuchsia.component/realm.fidl
<EMPTY>
Realm_DestroyChild_Response
Defined in fuchsia.component/realm.fidl
<EMPTY>
Realm_ListChildren_Response
Defined in fuchsia.component/realm.fidl
<EMPTY>
Realm_OpenExposedDir_Response
Defined in fuchsia.component/realm.fidl
<EMPTY>
ENUMS
Error strict
Type: uint32
Defined in fuchsia.component/error.fidl
Standard error codes for component framework protocols.
Name | Value | Description |
---|---|---|
INTERNAL |
1 |
Component manager encountered an otherwise unspecified error while performing the operation. |
INVALID_ARGUMENTS |
2 |
At least one argument had an invalid format. |
UNSUPPORTED |
3 |
The feature is not yet supported. |
ACCESS_DENIED |
4 |
The caller did not have permission to perform the specified operation, or one of the handles provided to the call had insufficient rights. |
INSTANCE_NOT_FOUND |
5 |
The component instance was not found. |
INSTANCE_ALREADY_EXISTS |
6 |
The component instance already exists. |
INSTANCE_CANNOT_START |
7 |
The component instance could not be started. |
INSTANCE_CANNOT_RESOLVE |
8 |
Failed to resolve the component's declaration. |
COLLECTION_NOT_FOUND |
9 |
The component collection was not found. |
RESOURCE_UNAVAILABLE |
10 |
There were insufficient resources to perform the operation. |
INSTANCE_DIED |
11 |
The component instance died unexpectedly. |
RESOURCE_NOT_FOUND |
12 |
The requested resource does not exist. |
TABLES
CreateChildArgs resource
Defined in fuchsia.component/realm.fidl
Ordinal | Field | Type | Description |
---|---|---|---|
1 |
numbered_handles |
vector<fuchsia.process/HandleInfo>[128]
|
The numbered handles to pass to the component instance. Only PA_FD and PA_USER* handles are valid arguments, and inclusion of any other
handles will result in an error. This argument is only supported for components
in a collection with If the runner for the component does not support the numbered handles it is expected to close the handles. |
2 |
dynamic_offers |
vector<fuchsia.component.decl/Offer>[128]
|
Dynamic offers that will target the component instance. Including Any kind of offer (e.g., protocol, directory) can be used as a dynamic
offer. Any source that would be valid for a static offer is also valid
for a dynamic offer. Additionally, unlike static offers, dynamic offers
can use a "sibling" dynamic child component as a source by setting the
source to a Dynamic offers always target the newly created child component. As a
result, If either the source (that is, the component named in the In order to set this field to a non-empty value, the collection in which
the child component is being created must specify
TODO(fxbug.dev/81109): Implementation is in progress. |
UNIONS
Realm_CreateChild_Result strict
Defined in fuchsia.component/realm.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
Realm_CreateChild_Response
|
|
2 |
err |
Error
|
Realm_DestroyChild_Result strict
Defined in fuchsia.component/realm.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
Realm_DestroyChild_Response
|
|
2 |
err |
Error
|
Realm_ListChildren_Result strict
Defined in fuchsia.component/realm.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
Realm_ListChildren_Response
|
|
2 |
err |
Error
|
Realm_OpenExposedDir_Result strict
Defined in fuchsia.component/realm.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
Realm_OpenExposedDir_Response
|
|
2 |
err |
Error
|
CONSTANTS
Name | Value | Type | Description |
---|---|---|---|
MAX_CHILD_COUNT |
128
|
uint32 |
The maximum number of children that the a call |
MAX_CHILD_NAME_LENGTH |
1024
|
uint32 |
|
MAX_DYNAMIC_OFFER_COUNT |
128
|
uint32 |
The maximum number of dynamic offers that can target a created component. |
MAX_HANDLE_COUNT |
128
|
uint32 |
The maximum number of handles that can be passed to a created component. |
MAX_MONIKER_LENGTH |
4096
|
uint32 |
|
MAX_NAME_LENGTH |
100
|
uint32 |
|
MAX_NUM_EVENTS_RECEIVED |
100
|
uint64 |
The maximum number of events that a receiver can listen to. |
MAX_PATH_LENGTH |
1024
|
uint32 |
|
MAX_SUBSCRIPTION_REQUESTS |
2
|
uint32 |
The maximum number of requests per event subscription. |
MAX_URL_SCHEME_LENGTH |
100
|
uint32 |
TYPE ALIASES
Name | Value | Description |
---|---|---|
child_name |
string [MAX_CHILD_NAME_LENGTH ] |
|
name |
string [MAX_NAME_LENGTH ] |
|
url_scheme |
string [MAX_URL_SCHEME_LENGTH ] |