fuchsia.component

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.

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

Controller

Defined in fuchsia.component/controller.fidl

A protocol used to operate on a component.

One may get access to a Controller when creating a component with the Realm.CreateChild method. You may also obtain a Controller for an existing child component with the Realm.OpenController method.

Destroy

Destroys this component. When this method returns, either:

• Ok was returned, indicating destruction has begun.
• An error was returned, and destruction will not be attempted.

If Ok was returned, destruction will proceed in the background, but it hasn't necessarily completed yet. When it completes, the framework will close this [Controller] channel.

Errors:

• ACCESS_DENIED: Destruction of this component is not allowed. Currently, this can happen if the component is a static child of its parent.

Request

<EMPTY>

Response

Name	Type
payload	Controller_Destroy_Result

GetExposedDictionary

Returns the dictionary containing the component's exposed capabilities.

Request

<EMPTY>

Response

Name	Type
payload	Controller_GetExposedDictionary_Result

IsStarted

Returns true if this instance is currently running.

Request

<EMPTY>

Response

Name	Type
payload	Controller_IsStarted_Result

Start

Start the component, optionally providing additional handles to be given to the component. Returns INSTANCE_ALREADY_RUNNING if the instance is currently running.

Request

Name	Type
args	StartChildArgs
execution_controller	server_end:ExecutionController

Response

Name	Type
payload	Controller_Start_Result

EventStream

Defined in fuchsia.component/events.fidl

Listener for events on the component hierarchy. Can't be used outside of the platform.

GetNext

Request

<EMPTY>

Response

Name	Type
events	vector<Event>

WaitForReady

Returns immediately. Used to indicate that the FIDL connection completed. This is needed for non-static streams to verify that subscribe has completed before components are started.

Request

<EMPTY>

Response

<EMPTY>

ExecutionController

Defined in fuchsia.component/controller.fidl

OnStop

When the child is stopped due to Stop being called, the child exiting on its own, or for any other reason, OnStop is called and then this channel is closed.

Response

Name	Type
stopped_payload	StoppedPayload

Stop

Initiates a stop action on this component. Once complete, OnStop will be called with the stopped payload and this channel is closed.

Note that a component may stop running on its own at any time, so it is possible for OnStop to be received before Stop is called.

Request

<EMPTY>

Introspector

Defined in fuchsia.component/introspector.fidl

A protocol used by a component instance to obtain information about components in its own realm.

This protocol only supports getting the moniker at the moment but could expand to other privileged information such as the URL of a component.

The component framework provides this capability to components that use fuchsia.component.Introspector from framework.

GetMoniker

Obtains the moniker relative to this realm of the component corresponding to the provided token. Runners may obtain the token via fuchsia.component.runner/ComponentStartInfo.component_instance.

Returns Error.INSTANCE_NOT_FOUND if the token is invalid, or does not correspond to a component under this realm.

Request

Name	Type
component_instance	handle<event>

Response

Name	Type
payload	Introspector_GetMoniker_Result

Namespace

Defined in fuchsia.component/namespace.fidl

Protocol for performing namespace operations.

Create

Request

Name	Type
entries	vector<NamespaceInputEntry>

Response

Name	Type
payload	Namespace_Create_Result

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.

If decl.startup == EAGER, or collection.durability == SINGLE_RUN, [CreateChild] will start the component and return once the component is started. Otherwise, [CreateChild] will return immediately after creating the component and will not start or resolve it.

Errors:

• INVALID_ARGUMENTS: collection is not a valid reference or child is not a valid declaration.
• COLLECTION_NOT_FOUND: collection does not exist.
• INSTANCE_ALREADY_EXISTS: decl.name already exists in collection.
• INSTANCE_CANNOT_RESOLVE: child's component declaration failed to resolve in a SingleRun 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
payload	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
payload	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 or iter does not have ZX_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 return ACCESS_DENIED or component manager may close iter.

Request

Name	Type
collection	fuchsia.component.decl/CollectionRef
iter	server_end:ChildIterator

Response

Name	Type
payload	Realm_ListChildren_Result

OpenController

Operate on a child component. See documentation for Controller.

Errors:

• INVALID_ARGUMENTS: child is not a valid child reference.
• INSTANCE_NOT_FOUND: child does not exist.
• INSTANCE_DIED: This realm no longer exists.

Request

Name	Type
child	fuchsia.component.decl/ChildRef
controller	server_end:Controller

Response

Name	Type
payload	Realm_OpenController_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	server_end:fuchsia.io/Directory

Response

Name	Type
payload	Realm_OpenExposedDir_Result

STRUCTS

Controller_Destroy_Response

Defined in fuchsia.component/controller.fidl

<EMPTY>

Controller_GetExposedDictionary_Response resource

Defined in fuchsia.component/controller.fidl

Field	Type	Description	Default
dictionary	fuchsia.component.sandbox/DictionaryRef		No default

Controller_IsStarted_Response resource

Defined in fuchsia.component/controller.fidl

Field	Type	Description	Default
is_started	bool		No default

Controller_Start_Response

Defined in fuchsia.component/controller.fidl

<EMPTY>

Introspector_GetMoniker_Response

Defined in fuchsia.component/introspector.fidl

Field	Type	Description	Default
moniker	string:4096		No default

NamespaceInputEntry resource

Defined in fuchsia.component/namespace.fidl

Field	Type	Description	Default
path	string:4095		No default
dictionary	client_end:fuchsia.component.sandbox/Dictionary		No default

Namespace_Create_Response resource

Defined in fuchsia.component/namespace.fidl

Field	Type	Description	Default
entries	vector<NamespaceEntry>		No default

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_OpenController_Response

Defined in fuchsia.component/realm.fidl

<EMPTY>

Realm_OpenExposedDir_Response

Defined in fuchsia.component/realm.fidl

<EMPTY>

ENUMS

Error flexible

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.
INSTANCE_CANNOT_UNRESOLVE	13	Failed to unresolve the component.
INSTANCE_ALREADY_STARTED	14	The component instance has already been started. Added: 14

EventType strict

Type: uint32

Defined in fuchsia.component/events.fidl

These EventTypes are used for the EventStream protocol. They are FIDL versions of the EventType enum in hooks.rs and have the same meaning.

Name	Value	Description
CAPABILITY_REQUESTED	1	A capability provided by this component has been requested. The event payload carries the request channel.
DIRECTORY_READY	2	A directory exposed to the framework by a component is available. Removed: 20
DISCOVERED	3	A component instance was discovered. This is the first stage in the lifecycle of components. Dispatched for dynamic children when they're created, for static children when their parent is resolved, and for the root when the component manager starts.
DESTROYED	4	The instance is destroyed and no longer exists.
RESOLVED	5	An instance's declaration was resolved successfully for the first time.
STARTED	6	This instance has started, according to component manager. However, if this is an executable component, the runner has further work to do to launch the component.
STOPPED	7	An instance was stopped successfully.
DEBUG_STARTED	8	Similar to STARTED, except the payload will carry an eventpair that the subscriber could use to defer the launch of the component. This allows, e.g., a debugger to perform some setup before any processes are created.
UNRESOLVED	9	An instance was unresolved successfully.

NamespaceError flexible

Type: uint32

Defined in fuchsia.component/namespace.fidl

Error returned from methods in Namespace.

Name	Value	Description
SHADOW	1	The parent of a parent shares a prefix with another namespace entry
DUPLICATE	2	Two entries have the same namespace path.
CONVERSION	3	Failed to convert a namespace dictionary to a directory.
BAD_ENTRY	4	A namespace entry was invalid.
DICTIONARY_READ	5	There was an error reading from one of the dictionaries.

TABLES

CapabilityRequestedPayload resource

Defined in fuchsia.component/events.fidl

Payload for CapabilityRequested events

Ordinal	Field	Type	Description
1	name	name	The name of the capability.
2	capability	handle<channel>	A handle to the server end of the channel to host capability.

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. 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 OfferDecls in this vector will cause additional capabilities to be offered to the newly created child, beyond the OfferDecls in the parent's ComponentDecl that target the collection. 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 ChildRef that sets the collection field. Dynamic offers always target the newly created child component. As a result, OfferDecls in dynamic_offers must not set the target field, as its value is implied. If either the source (that is, the component named in the source field of the OfferDecl) or the target of a dynamic offer is destroyed, the offer itself is destroyed simultaneously. In order to set this field to a non-empty value, the collection in which the child component is being created must specify ComponentDecl.allowed_offers = STATIC_AND_DYNAMIC.
3	controller	server_end:Controller	The controller for this component, which may be used to influence the component's lifecycle. Added: 14
4	dictionary	fuchsia.component.sandbox/DictionaryRef	A dictionary that contains extra capabilities for the component instance. Added: HEAD

DebugStartedPayload resource

Defined in fuchsia.component/events.fidl

Payload for DebugStarted events.

Ordinal	Field	Type	Description
1	runtime_dir	client_end:fuchsia.io/Directory	The directory served by the runner to present runtime and runner-specific information about the component. The other side is sent to the runner in ComponentStartInfo. For example, it can be queried to know whether the component is an ELF component and supports the break_on_start protocol below.
2	break_on_start	handle<eventpair>	An eventpair that can be used by debuggers to defer the launch of the component, e.g., ELF debuggers can setup the exception channel on the job while holding the eventpair, then drop the eventpair to notify the runner that processes could be created. The other side is sent to the runner in ComponentStartInfo.

DestroyedPayload

Defined in fuchsia.component/events.fidl

Payload for Destroyed events.

Ordinal	Field	Type	Description

DirectoryReadyPayload resource

Defined in fuchsia.component/events.fidl

Payload for DirectoryReady events

Ordinal	Field	Type	Description
1	name	name	The name of the capability.
2	node	client_end:fuchsia.io/Node	Channel to the directory capability.

DiscoveredPayload

Defined in fuchsia.component/events.fidl

Payload for Discovered events.

Ordinal	Field	Type	Description

Event resource

Defined in fuchsia.component/events.fidl

Contains all information about a single event

Ordinal	Field	Type	Description
1	header	EventHeader	Information about the component for which this event was generated.
2	payload	EventPayload	Optional payload for some event types

EventHeader

Defined in fuchsia.component/events.fidl

A head providing metadata about a target component instance.

Ordinal	Field	Type	Description
1	event_type	EventType	Event type corresponding to the event
2	moniker	string:4096	Relative moniker identifying the component instance. Relative to the scope of the event.
3	component_url	fuchsia.url/Url	URL used to resolve the component.
4	timestamp	zx/InstantBoot	Boot time when the event occurred. Added: 25

NamespaceEntry resource

Defined in fuchsia.component/controller.fidl

A single component namespace entry, which describes a namespace mount point (path) and the directory backing it (directory). This type is usually composed inside a vector. See ComponentStartInfo.ns for more details.

Ordinal	Field	Type	Description
1	path	string:4095	The mount point for the directory, including a leading slash. For example: "/pkg", "/svc", or "/config/data".
2	directory	client_end:fuchsia.io/Directory	The directory mounted at the above path.

PurgedPayload

Defined in fuchsia.component/events.fidl

Payload for Purged events.

Ordinal	Field	Type	Description

ResolvedPayload

Defined in fuchsia.component/events.fidl

Payload for Resolved events.

Ordinal	Field	Type	Description

StartChildArgs resource

Defined in fuchsia.component/controller.fidl

Ordinal	Field	Type	Description
1	numbered_handles	vector<fuchsia.process/HandleInfo>:128	The numbered handles to pass to the component instance. If the runner for the component does not support the numbered handles it is expected to close the handles. If set, the values given here will override the handles given in CreateChildArgs.
2	namespace_entries	vector<NamespaceEntry>:32	The namespace generated by component manager will be extended to include any namespace entries listed here before being given to the component's runner. If there are any conflicting entries, an error will occur when starting the component.
3	dictionary	fuchsia.component.sandbox/DictionaryRef	A dictionary that contains extra capabilities for the component instance. Added: HEAD

StartedPayload

Defined in fuchsia.component/events.fidl

Payload for Started events.

Ordinal	Field	Type	Description

StoppedPayload

Defined in fuchsia.component/events.fidl

Payload for Stopped events.

Ordinal	Field	Type	Description
1	status	zx/Status	The epitaph set on the fuchsia.component.runner/ComponentController protocol channel. This is the exit status of the component. The possible status values and their meaning are described in the definition of the ComponentController protocol.
2	exit_code	int64	The exit code of the component instance. Note that not all components will stop with an exit code. Many program runtimes have the concept of an exit code. Runners may map that value to this field when applicable. For example, the ELF runner will publish the Zircon process return code here. Added: 23

UnresolvedPayload

Defined in fuchsia.component/events.fidl

Payload for Unresolved events.

Ordinal	Field	Type	Description

UNIONS

Controller_Destroy_Result strict

Defined in fuchsia.component/controller.fidl

Ordinal	Variant	Type	Description
1	response	Controller_Destroy_Response
2	err	Error
3	framework_err	internal

Controller_GetExposedDictionary_Result strict resource

Defined in fuchsia.component/controller.fidl

Ordinal	Variant	Type	Description
1	response	Controller_GetExposedDictionary_Response
2	err	Error
3	framework_err	internal

Controller_IsStarted_Result strict resource

Defined in fuchsia.component/controller.fidl

Ordinal	Variant	Type	Description
1	response	Controller_IsStarted_Response
2	err	Error
3	framework_err	internal

Controller_Start_Result strict

Defined in fuchsia.component/controller.fidl

Ordinal	Variant	Type	Description
1	response	Controller_Start_Response
2	err	Error
3	framework_err	internal

EventPayload flexible resource

Defined in fuchsia.component/events.fidl

Encapsulates additional data/protocols for some event types.

Ordinal	Variant	Type	Description
1	capability_requested	CapabilityRequestedPayload	Payload for CapabilityRequested events
2	purged	PurgedPayload	Payload for Purged events.
3	directory_ready	DirectoryReadyPayload	Payload for DirectoryReady events Removed: 20 Deprecated: 19
4	discovered	DiscoveredPayload	Payload for Discovered events. Deprecated: 22
5	destroyed	DestroyedPayload	Payload for Destroyed events.
6	resolved	ResolvedPayload	Payload for Resolved events
7	started	StartedPayload	Payload for Started events
8	stopped	StoppedPayload	Payload for Stopped events
9	debug_started	DebugStartedPayload	Payload for DebugStarted events
10	unresolved	UnresolvedPayload	Payload for Unresolved events

Introspector_GetMoniker_Result strict

Defined in fuchsia.component/introspector.fidl

Ordinal	Variant	Type	Description
1	response	Introspector_GetMoniker_Response
2	err	Error
3	framework_err	internal

Namespace_Create_Result strict resource

Defined in fuchsia.component/namespace.fidl

Ordinal	Variant	Type	Description
1	response	Namespace_Create_Response
2	err	NamespaceError
3	framework_err	internal

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_OpenController_Result strict

Defined in fuchsia.component/realm.fidl

Ordinal	Variant	Type	Description
1	response	Realm_OpenController_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_CAPABILITY_ID_LENGTH	50	uint64	The maximum string length of a capability ID. This value is currently set arbitrarily. Added: 11
MAX_CHILD_COUNT	128	uint32	The maximum number of children that the a call ChildIterator.Next can return. Note, this is not a limit on the number of children that can be added to a component. This is merely a limit for a single invocation of the Next method.
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_ERROR_DESCRIPTION_LENGTH	100	uint64	The maximum string length of an error description. Added: 11
MAX_HANDLE_COUNT	128	uint32	The maximum number of handles that can be passed to a created component.
MAX_MONIKER_LENGTH	4096	uint32
MAX_NAMESPACE_COUNT	32	uint32	Added: 14
MAX_NAME_LENGTH	fuchsia.io/MAX_NAME_LENGTH	uint64	Added: 19
MAX_NUM_EVENTS_RECEIVED	100	uint64	The maximum number of events that a receiver can listen to.
MAX_PATH_LENGTH	fuchsia.io/MAX_PATH_LENGTH	uint64	Added: 15
MAX_SUBSCRIPTION_REQUESTS	2	uint32	The maximum number of requests per event subscription.
MAX_URL_SCHEME_LENGTH	MAX_NAME_LENGTH	uint64	Added: 19

ALIASES

Name	Value	Description
child_name	string[MAX_CHILD_NAME_LENGTH]
name	string[MAX_NAME_LENGTH]
url_scheme	string[MAX_URL_SCHEME_LENGTH]