Google Celebrates Black History Month. See how.

fuchsia.component

Added: 7

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

NameType
children vector<fuchsia.component.decl/ChildRef>[128]

EventStream

Defined in fuchsia.component/events.fidl

Listener for events on the component hierarchy.

Added: 11

GetNext

Request

<EMPTY>

Response

NameType
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>

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

NameType
collection fuchsia.component.decl/CollectionRef
decl fuchsia.component.decl/Child
args CreateChildArgs

Response

NameType
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

NameType
child fuchsia.component.decl/ChildRef

Response

NameType
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 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

NameType
collection fuchsia.component.decl/CollectionRef
iter server_end<ChildIterator>

Response

NameType
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

NameType
child fuchsia.component.decl/ChildRef
exposed_dir server_end<fuchsia.io/Directory>

Response

NameType
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.

NameValueDescription
1

Component manager encountered an otherwise unspecified error while performing the operation.
2

At least one argument had an invalid format.
3

The feature is not yet supported.
4

The caller did not have permission to perform the specified operation, or one of the handles provided to the call had insufficient rights.
5

The component instance was not found.
6

The component instance already exists.
7

The component instance could not be started.
8

Failed to resolve the component's declaration.
9

The component collection was not found.
10

There were insufficient resources to perform the operation.
11

The component instance died unexpectedly.
12

The requested resource does not exist.
13

Failed to unresolve the component.

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.

Added: 11

NameValueDescription
1

A capability provided by this component has been requested. The event payload carries the request channel.
2

A directory exposed to the framework by a component is available.
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.
4

The instance is destroyed and no longer exists.
5

An instance's declaration was resolved successfully for the first time.
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.
7

An instance was stopped successfully.
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.
9

An instance was unresolved successfully.

TABLES

CapabilityRequestedPayload resource

Defined in fuchsia.component/events.fidl

Payload for CapabilityRequested events

Added: 11

OrdinalFieldTypeDescription
name name

The name of the capability.
capability handle<channel>

A handle to the server end of the channel to host capability.

CreateChildArgs resource

Defined in fuchsia.component/realm.fidl

OrdinalFieldTypeDescription
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 SingleRun durability.

If the runner for the component does not support the numbered handles it is expected to close the handles.
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.

DebugStartedPayload resource

Defined in fuchsia.component/events.fidl

Payload for DebugStarted events.

Added: 11

OrdinalFieldTypeDescription
runtime_dir 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.
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.

Added: 11

OrdinalFieldTypeDescription

DirectoryReadyPayload resource

Defined in fuchsia.component/events.fidl

Payload for DirectoryReady events

Added: 11

OrdinalFieldTypeDescription
name name

The name of the capability.
node fuchsia.io/Node

Channel to the directory capability.

DiscoveredPayload

Defined in fuchsia.component/events.fidl

Payload for Discovered events.

Added: 11

OrdinalFieldTypeDescription

Event resource

Defined in fuchsia.component/events.fidl

Contains all information about a single event

Added: 11

OrdinalFieldTypeDescription
header EventHeader

Information about the component for which this event was generated.
payload EventPayload

Optional payload for some event types

EventHeader

Defined in fuchsia.component/events.fidl

A head providing metadata about a target component instance.

Added: 11

OrdinalFieldTypeDescription
event_type EventType

Event type corresponding to the event
moniker string[4096]

Relative moniker identifying the component instance. Relative to the scope of the event.
component_url fuchsia.url/Url

URL used to resolve the component.
timestamp zx/time

Time when the event occurred.

PurgedPayload

Defined in fuchsia.component/events.fidl

Payload for Purged events.

Added: 11

OrdinalFieldTypeDescription

ResolvedPayload

Defined in fuchsia.component/events.fidl

Payload for Resolved events.

Added: 11

OrdinalFieldTypeDescription

StartedPayload

Defined in fuchsia.component/events.fidl

Payload for Started events.

Added: 11

OrdinalFieldTypeDescription

StoppedPayload

Defined in fuchsia.component/events.fidl

Payload for Stopped events.

Added: 11

OrdinalFieldTypeDescription
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.

UnresolvedPayload

Defined in fuchsia.component/events.fidl

Payload for Unresolved events.

Added: 11

OrdinalFieldTypeDescription

UNIONS

EventPayload flexible resource

Defined in fuchsia.component/events.fidl

Encapsulates additional data/protocols for some event types.

Added: 11
OrdinalVariantTypeDescription
capability_requested CapabilityRequestedPayload

Payload for CapabilityRequested events
purged PurgedPayload

Payload for Purged events.
directory_ready DirectoryReadyPayload

Payload for DirectoryReady events
discovered DiscoveredPayload

Payload for Discovered events.
destroyed DestroyedPayload

Payload for Destroyed events.
resolved ResolvedPayload

Payload for Resolved events
started StartedPayload

Payload for Started events
stopped StoppedPayload

Payload for Stopped events
debug_started DebugStartedPayload

Payload for DebugStarted events
unresolved UnresolvedPayload

Payload for Unresolved events

Realm_CreateChild_Result strict

Defined in fuchsia.component/realm.fidl

OrdinalVariantTypeDescription
response Realm_CreateChild_Response
err Error

Realm_DestroyChild_Result strict

Defined in fuchsia.component/realm.fidl

OrdinalVariantTypeDescription
response Realm_DestroyChild_Response
err Error

Realm_ListChildren_Result strict

Defined in fuchsia.component/realm.fidl

OrdinalVariantTypeDescription
response Realm_ListChildren_Response
err Error

Realm_OpenExposedDir_Result strict

Defined in fuchsia.component/realm.fidl

OrdinalVariantTypeDescription
response Realm_OpenExposedDir_Response
err Error

CONSTANTS

NameValueTypeDescription
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_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

ALIASES

NameValueDescription
child_name string[MAX_CHILD_NAME_LENGTH]
name string[MAX_NAME_LENGTH]
url_scheme string[MAX_URL_SCHEME_LENGTH]