fuchsia.component.sandbox

PROTOCOLS

Dictionary

Defined in fuchsia.component.sandbox/sandbox.fidl

Clone

Creates a new connection to the same underlying dictionary.

Use Copy to a new dictionary with clones of all the exiting entries.

Request

<EMPTY>

Response

Name	Type
payload	Dictionary_Clone_Result

Copy

Create a new dictionary that contains a clone of all the entries in this dictionary.

For example, if this dictionary contains nested dictionaries, the newly created dictionary will contain references to those same nested dictionaries because the entries are cloned rather than copied.

Request

<EMPTY>

Response

Name	Type
payload	Dictionary_Copy_Result

Drain

Removes all the entries in this dictionary.

If contents is not provided, all the items are discarded without enumerating them.

Request

Name	Type
contents	server_end<DictionaryIterator>?

Enumerate

Enumerates the entries in this dictionary.

Creates a clone of each item during enumeration.

Request

Name	Type
contents	server_end<DictionaryIterator>

Get

Get a clone of a capability from this dictionary.

• error DictionaryError.NOT_FOUND if the dictionary does not contain the key.

Request

Name	Type
key	DictionaryKey

Response

Name	Type
payload	Dictionary_Get_Result

Insert

Inserts a key-value pair into the dictionary.

• error DictionaryError.ALREADY_EXISTS if the dictionary already contains an item with the same key.

Request

Name	Type
key	DictionaryKey
value	Capability

Response

Name	Type
payload	Dictionary_Insert_Result

Read

Returns all items in this dictionary, sorted by key in natural order.

This operation creates shallow clones of values.

Request

<EMPTY>

Response

Name	Type
payload	Dictionary_Read_Result

Remove

Removes a key from the dictionary, returning the Capability value.

• error DictionaryError.NOT_FOUND if the dictionary does not contain the key.

Request

Name	Type
key	DictionaryKey

Response

Name	Type
payload	Dictionary_Remove_Result

DictionaryIterator

Defined in fuchsia.component.sandbox/sandbox.fidl

GetNext

Request

<EMPTY>

Response

Name	Type
payload	DictionaryIterator_GetNext_Result

Factory

Defined in fuchsia.component.sandbox/sandbox.fidl

The Factory protocol handles:

• Instantiation of sandbox types.
• Controlling sandbox objects given tokens.

CreateConnector

Creates a Connector from a client served Receiver.

Request

Name	Type
receiver	Receiver

Response

Name	Type
payload	Factory_CreateConnector_Result

CreateDictionary

Creates a new empty Dictionary.

Request

<EMPTY>

Response

Name	Type
payload	Factory_CreateDictionary_Result

CreateOneShotHandle

Creates a OneShotHandle from the provided handle.

Request

Name	Type
handle	handle<handle>

Response

Name	Type
payload	Factory_CreateOneShotHandle_Result

OpenConnector

Open a connection from the provided [Connector] capability.

If there is an error, it will be reported as a zx.Status epitaph on server_end. Errors:

• INVALID_ARGS: capability is not a recognized [Connector].

Request

Name	Type
capability	Connector
server_end	handle<channel>

TakeHandle

Extract the handle owned by the underlying capability, if it wasn't taken already.

Errors:

• INVALID_ARGS: capability does not contain a recognized [OneShotHandle] token.
• UNAVAILABLE: The underlying handle was already taken.h

Request

Name	Type
capability	OneShotHandle

Response

Name	Type
payload	Factory_TakeHandle_Result

Receiver

Defined in fuchsia.component.sandbox/sandbox.fidl

A receiver is served by clients and allows them to receive channels from the framework.

Receive

Sends a channel to this receiver.

Request

Name	Type
channel	handle<channel>

Router

Defined in fuchsia.component.sandbox/sandbox.fidl

A router allows a client to request a capability.

Route

Request

Name	Type
payload	RouteRequest

Response

Name	Type
payload	Router_Route_Result

STRUCTS

ComponentToken resource

Defined in fuchsia.component.sandbox/sandbox.fidl

This represents a component within the framework. There are currently no methods here as this is used as a token.

Field	Type	Description	Default
token	handle<eventpair>		No default

Connector resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
token	handle<eventpair>		No default

DictionaryItem resource

Defined in fuchsia.component.sandbox/sandbox.fidl

A key-value pair in a Dictionary.

Field	Type	Description	Default
key	DictionaryKey		No default
value	Capability		No default

DictionaryIterator_GetNext_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
items	vector<DictionaryItem>[128]		No default

Dictionary_Clone_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
dictionary	Dictionary		No default

Dictionary_Copy_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
dictionary	Dictionary		No default

Dictionary_Get_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
capability	Capability		No default

Dictionary_Insert_Response

Defined in fuchsia.component.sandbox/sandbox.fidl

<EMPTY>

Dictionary_Read_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
items	vector<DictionaryItem>		No default

Dictionary_Remove_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
capability	Capability		No default

Factory_CreateConnector_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
capability	Connector		No default

Factory_CreateDictionary_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
dictionary	Dictionary		No default

Factory_CreateOneShotHandle_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
capability	OneShotHandle		No default

Factory_TakeHandle_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
handle	handle<handle>		No default

OneShotHandle resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
token	handle<eventpair>		No default

ProtocolPayload resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Contains a protocol open request.

Field	Type	Description	Default
channel	handle<channel>		No default

Router_Route_Response resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Field	Type	Description	Default
capability	Capability		No default

UnitCapability

Defined in fuchsia.component.sandbox/sandbox.fidl

<EMPTY>

ENUMS

Availability strict

Type: uint32

Defined in fuchsia.component.sandbox/availability.fidl

Describes the expected availability of the capability.

Some capabilities may not be present on all system configurations. In those cases, the availability will be declared as OPTIONAL along the chains of exposes/offers/uses, and the capability would be routed from void on system configurations where it does not make sense to route or provide a particular capability (e.g. graphical capabilities on a headless system).

Name	Value	Description
REQUIRED	1	The capability must be available. Failure to route the capability is an error.
OPTIONAL	2	Inside a use declaration: the component can function if it fails to obtain the capability. Inside an offer/expose declaration: the capability may not be available in some system configurations. As a corollary, the target component must not have a required dependency on the capability.
SAME_AS_TARGET	3	If the target of the corresponding offer or expose declaration requires the capability, then the behavior is equivalent to required. If the target has an optional dependency on the capability, then the behavior is equivalent to optional. This is useful for container components that would like to change their routing availability based on ones inside. This value is not allowed inside a use declaration.
TRANSITIONAL	4	The source may omit the route completely without even having to route from void. TRANSITIONAL is used for soft transitions that introduce new capabilities.

DictionaryError flexible

Type: uint32

Defined in fuchsia.component.sandbox/sandbox.fidl

Error returned from methods in Dictionary.

Name	Value	Description
NOT_FOUND	1	The Dictionary does not contain an item with the given key.
ALREADY_EXISTS	2	The Dictionary already contains an item with the given key.
BAD_CAPABILITY	3	The Capability is invalid. Capabilities must be created by sandbox, via fuchsia.component.sandbox.Factory or returned from other Component Framework APIs.
INVALID_KEY	4	The key is invalid. The constraints for valid keys are documented at https://fuchsia.dev/reference/cml#names.

FactoryError flexible

Type: uint32

Defined in fuchsia.component.sandbox/sandbox.fidl

Name	Value	Description
INVALID_ARGS	1	An invalid argument was passed.
UNAVAILABLE	2	The requested resource was unavailable.

RouterError flexible

Type: uint32

Defined in fuchsia.component.sandbox/sandbox.fidl

Name	Value	Description
NOT_FOUND	1	The router failed to find the capability.
INVALID_ARGS	2	The arguments provided to the function are invalid.

TABLES

RouteRequest resource

Defined in fuchsia.component.sandbox/sandbox.fidl

A request for a route.

Ordinal	Field	Type	Description
1	availability	Availability	The requested availability for this capability.
2	requesting	ComponentToken	The component that is requesting the capability.

UNIONS

Capability flexible resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	unit	UnitCapability
2	handle	OneShotHandle
3	data	DataCapability
4	dictionary	Dictionary
5	connector	Connector
6	directory	fuchsia.io/Directory
7	router	Router

DataCapability flexible

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	bytes	vector<uint8>[8192]
2	string	string[8192]
3	int64	int64
4	uint64	uint64

DictionaryIterator_GetNext_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	DictionaryIterator_GetNext_Response
3	framework_err	internal

Dictionary_Clone_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Dictionary_Clone_Response
3	framework_err	internal

Dictionary_Copy_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Dictionary_Copy_Response
3	framework_err	internal

Dictionary_Get_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Dictionary_Get_Response
2	err	DictionaryError
3	framework_err	internal

Dictionary_Insert_Result strict

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Dictionary_Insert_Response
2	err	DictionaryError
3	framework_err	internal

Dictionary_Read_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Dictionary_Read_Response
3	framework_err	internal

Dictionary_Remove_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Dictionary_Remove_Response
2	err	DictionaryError
3	framework_err	internal

Factory_CreateConnector_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Factory_CreateConnector_Response
3	framework_err	internal

Factory_CreateDictionary_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Factory_CreateDictionary_Response
3	framework_err	internal

Factory_CreateOneShotHandle_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Factory_CreateOneShotHandle_Response
3	framework_err	internal

Factory_TakeHandle_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Factory_TakeHandle_Response
2	err	FactoryError
3	framework_err	internal

Router_Route_Result strict resource

Defined in fuchsia.component.sandbox/sandbox.fidl

Ordinal	Variant	Type	Description
1	response	Router_Route_Response
2	err	RouterError
3	framework_err	internal

CONSTANTS

Name	Value	Type	Description
MAX_DATA_LENGTH	8192	uint32	Maximum number of bytes in a [DataCapability].
MAX_DICTIONARY_ITEMS_CHUNK	128	uint32	Maximum number of items returned by [DictionaryIterator].
MAX_NAME_LENGTH	fuchsia.io/MAX_NAME_LENGTH	uint64	The maximum length of a dictionary key. This should coincide with fuchsia.component.MAX_NAME_LENGTH. Added: HEAD

ALIASES

Name	Value	Description
DictionaryKey	string[MAX_NAME_LENGTH]	The key of a DictionaryItem. The constraints for valid keys are documented at https://fuchsia.dev/reference/cml#names. Added: HEAD