Enum CapabilityStoreRequest

pub enum CapabilityStoreRequest {
    Duplicate {
        id: u64,
        dest_id: u64,
        responder: CapabilityStoreDuplicateResponder,
    },
    Drop {
        id: u64,
        responder: CapabilityStoreDropResponder,
    },
    Export {
        id: u64,
        responder: CapabilityStoreExportResponder,
    },
    Import {
        id: u64,
        capability: Capability,
        responder: CapabilityStoreImportResponder,
    },
    ConnectorCreate {
        id: u64,
        receiver: ClientEnd<ReceiverMarker>,
        responder: CapabilityStoreConnectorCreateResponder,
    },
    ConnectorOpen {
        id: u64,
        server_end: Channel,
        responder: CapabilityStoreConnectorOpenResponder,
    },
    DirConnectorCreate {
        id: u64,
        receiver: ClientEnd<DirReceiverMarker>,
        responder: CapabilityStoreDirConnectorCreateResponder,
    },
    DirConnectorOpen {
        id: u64,
        server_end: ServerEnd<DirectoryMarker>,
        responder: CapabilityStoreDirConnectorOpenResponder,
    },
    DictionaryCreate {
        id: u64,
        responder: CapabilityStoreDictionaryCreateResponder,
    },
    DictionaryLegacyImport {
        id: u64,
        client_end: Channel,
        responder: CapabilityStoreDictionaryLegacyImportResponder,
    },
    DictionaryLegacyExport {
        id: u64,
        server_end: Channel,
        responder: CapabilityStoreDictionaryLegacyExportResponder,
    },
    DictionaryInsert {
        id: u64,
        item: DictionaryItem,
        responder: CapabilityStoreDictionaryInsertResponder,
    },
    DictionaryGet {
        id: u64,
        key: String,
        dest_id: u64,
        responder: CapabilityStoreDictionaryGetResponder,
    },
    DictionaryRemove {
        id: u64,
        key: String,
        dest_id: Option<Box<WrappedCapabilityId>>,
        responder: CapabilityStoreDictionaryRemoveResponder,
    },
    DictionaryCopy {
        id: u64,
        dest_id: u64,
        responder: CapabilityStoreDictionaryCopyResponder,
    },
    DictionaryKeys {
        id: u64,
        iterator: ServerEnd<DictionaryKeysIteratorMarker>,
        responder: CapabilityStoreDictionaryKeysResponder,
    },
    DictionaryEnumerate {
        id: u64,
        iterator: ServerEnd<DictionaryEnumerateIteratorMarker>,
        responder: CapabilityStoreDictionaryEnumerateResponder,
    },
    DictionaryDrain {
        id: u64,
        iterator: Option<ServerEnd<DictionaryDrainIteratorMarker>>,
        responder: CapabilityStoreDictionaryDrainResponder,
    },
    _UnknownMethod {
        ordinal: u64,
        control_handle: CapabilityStoreControlHandle,
        method_type: MethodType,
    },
}

Protocol that represents the concept of a “capability store”, a repository for Capabilitys that are held by the component framework runtime.

[CapabilityStore] serves as the main bridge between the component runtime and clients that enables them to operate on and exchange Capabilitys. A [CapabilityStore] instance contains a set of Capabilitys, each of which has a CapabilityId assigned by the client.

Normally, a program would not exchange a [CapabilityStore] or CapabilityId with other programs – a [CapabilityStore] connection and its enclosed capabilities are intended to be “local” to a program. Instead, if a program wishes to exchange a Capability with other programs, it should [Export] the Capability out of the store, send the Capability to the target program, which can then [Import] the capability into its own store.

[CapabilityStore] is also used to manage capability lifetimes. The lifetime of a capability is scoped to the [CapabilityStore] in which it resides; i.e. to drop the [CapabilityStore] connections to release the capabilities instead it. In addition, [CapabilityStore] supports a Drop API to drop an individual Capability reference. (Note that it is possible for a some capabilities, like DictionaryRef, to have multiple references, in which case all of the references must be dropped for the underlying resource to be released.)

A note about semantics: the [CapabilityStore] APIs do not return CapabilityIds, because CapabilityIds are assigned by the client. Instead, when a method would semantically return a capability, this is expressed by taking the destination CapabilityId as an output parameter.

Variants

Duplicate

Duplicates the capability with id to dest_id.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• ID_ALREADY_EXISTS if a capability with dest_id already exists in this store.
• NOT_DUPLICATABLE if id could not be duplicated.

Fields

id: u64

dest_id: u64

responder: CapabilityStoreDuplicateResponder

Drop

Drops the capability with id from this [CapabilityStore].

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.

Fields

id: u64

responder: CapabilityStoreDropResponder

Export

Exports the capability with the client-assigned identifier id to capability. This operation removes the capability from the store. If this is not desired, [Duplicate] the capability first.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.

Fields

id: u64

responder: CapabilityStoreExportResponder

Import

Imports capability into this store with the client-assigned id.

Errors:

• ID_ALREADY_EXISTS if a capability with id already exists in this store.
• BAD_CAPABILITY if capability was not a valid Capability.

Fields

id: u64

capability: Capability

responder: CapabilityStoreImportResponder

ConnectorCreate

Creates a Connector from a [Receiver]. Incoming connections to the Connector will be dispatched to this [Receiver].

Errors:

• ID_ALREADY_EXISTS if a capability with id already exists in this store.

Fields

id: u64

receiver: ClientEnd<ReceiverMarker>

responder: CapabilityStoreConnectorCreateResponder

ConnectorOpen

Open a connection from the provided Connector capability that will be dispatched to the [Receiver] on the other end.

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

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• WRONG_TYPE if id was not a connector capability.

Fields

id: u64

server_end: Channel

responder: CapabilityStoreConnectorOpenResponder

DirConnectorCreate

Creates a DirConnector from a [DirReceiver]. Incoming connections to the DirConnector will be dispatched to this [DirReceiver].

Errors:

• ID_ALREADY_EXISTS if a capability with id already exists in this store.

Fields

id: u64

receiver: ClientEnd<DirReceiverMarker>

responder: CapabilityStoreDirConnectorCreateResponder

DirConnectorOpen

Open a connection from the provided DirConnector capability that will be dispatched to the [DirReceiver] on the other end.

This method does not take Open/Open3 parameters such as flags or path. Clients that wish to specify these can get an initial connection from this method and call fuchsia.io/Directory.Open on it. See the [DirReceiver] documentation for more information about the expectations of the server side.

If there was an error making the connection, it will be reported as a zx.Status epitaph on server_end.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• WRONG_TYPE if id was not a connector capability.

Fields

id: u64

server_end: ServerEnd<DirectoryMarker>

responder: CapabilityStoreDirConnectorOpenResponder

DictionaryCreate

Creates a new empty dictionary in this [CapabilityStore] with client-assigned id.

Errors:

• ID_ALREADY_EXISTS if a capability with id already exists in this store.

Fields

id: u64

responder: CapabilityStoreDictionaryCreateResponder

DictionaryLegacyImport

Imports a dictionary in the form of a channel.

This is a legacy API to support backward compatibility with APIs that take a [Dictionary] channel.

Errors:

• ID_ALREADY_EXISTS if a capability with id already exists in this store.
• BAD_CAPABILITY if client_end was not a valid dictionary channel.

Fields

id: u64

client_end: Channel

responder: CapabilityStoreDictionaryLegacyImportResponder

DictionaryLegacyExport

Binds a channel to the dictionary with id. The channel can be re-imported into a [CapabilityStore] with [DictionaryImportLegacy].

This is a legacy API to support backward compatibility with APIs that take a [Dictionary] channel.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.

Fields

id: u64

server_end: Channel

responder: CapabilityStoreDictionaryLegacyExportResponder

DictionaryInsert

Inserts item into the dictionary with id. item.value is moved into the dictionary and its id is released if this call succeeds.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• WRONG_TYPE if id was not a dictionary.
• INVALID_KEY if item.key was invalid.
• ITEM_ALREADY_EXISTS if the dictionary already contains an item with item.key.

Fields

id: u64

item: DictionaryItem

responder: CapabilityStoreDictionaryInsertResponder

DictionaryGet

Get a duplicate of a capability from the dictionary with id, which is loaded into dest_id.

Errors:

• ID_NOT_FOUND if id was not a recognized capability id in this store.
• ID_ALREADY_EXISTS if a capability with dest_id already exists in this store.
• WRONG_TYPE if id was not a dictionary.
• INVALID_KEY if item.key was invalid.
• ITEM_NOT_FOUND if the dictionary does not contain key.
• NOT_DUPLICATABLE if the capability could not be duplicated.

Fields

id: u64

key: String

dest_id: u64

responder: CapabilityStoreDictionaryGetResponder

DictionaryRemove

Removes a key from the dictionary with id. If dest_id is present, loads the value into it, otherwise discards the value.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• ID_ALREADY_EXISTS if a capability with dest_id already exists in this store.
• WRONG_TYPE if id was not a dictionary.
• INVALID_KEY if key was invalid.
• ITEM_NOT_FOUND if the dictionary does not contain the key.

Fields

id: u64

key: String

dest_id: Option<Box<WrappedCapabilityId>>

responder: CapabilityStoreDictionaryRemoveResponder

DictionaryCopy

Create a new dictionary that contains a duplicate of all the entries in the dictionary with id, assigning dest_id to the new dictionary. The runtime of this method is linear in the number of top-level entries in the dictionary.

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

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• ID_ALREADY_EXISTS if a capability with dest_id already exists in this store.
• WRONG_TYPE if id was not a dictionary.
• NOT_DUPLICATABLE if one of the capabilities in id could not be duplicated.

Fields

id: u64

dest_id: u64

responder: CapabilityStoreDictionaryCopyResponder

DictionaryKeys

Enumerates the keys in the dictionary with id.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• WRONG_TYPE if id was not a dictionary.

Fields

id: u64

iterator: ServerEnd<DictionaryKeysIteratorMarker>

responder: CapabilityStoreDictionaryKeysResponder

DictionaryEnumerate

Enumerates the items (keys and values) in the dictionary with id.

Creates a duplicate of each value (capability). If a value could not be duplicated, the value will be null.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• WRONG_TYPE if id was not a dictionary.

Fields

id: u64

iterator: ServerEnd<DictionaryEnumerateIteratorMarker>

responder: CapabilityStoreDictionaryEnumerateResponder

DictionaryDrain

Removes all the entries in this dictionary, returning them in contents if provided. If contents is not provided, all the items are discarded without enumerating them.

Errors:

• ID_NOT_FOUND if id was not a valid capability id in this store.
• WRONG_TYPE if id was not a dictionary.

Fields

id: u64

iterator: Option<ServerEnd<DictionaryDrainIteratorMarker>>

responder: CapabilityStoreDictionaryDrainResponder

_UnknownMethod

An interaction was received which does not match any known method.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

ordinal: u64

Ordinal of the method that was called.

control_handle: CapabilityStoreControlHandle

method_type: MethodType

Implementations

impl CapabilityStoreRequest

pub fn into_duplicate( self, ) -> Option<(u64, u64, CapabilityStoreDuplicateResponder)>

pub fn into_drop(self) -> Option<(u64, CapabilityStoreDropResponder)>

pub fn into_export(self) -> Option<(u64, CapabilityStoreExportResponder)>

pub fn into_import( self, ) -> Option<(u64, Capability, CapabilityStoreImportResponder)>

pub fn into_connector_create( self, ) -> Option<(u64, ClientEnd<ReceiverMarker>, CapabilityStoreConnectorCreateResponder)>

pub fn into_connector_open( self, ) -> Option<(u64, Channel, CapabilityStoreConnectorOpenResponder)>

pub fn into_dir_connector_create( self, ) -> Option<(u64, ClientEnd<DirReceiverMarker>, CapabilityStoreDirConnectorCreateResponder)>

pub fn into_dir_connector_open( self, ) -> Option<(u64, ServerEnd<DirectoryMarker>, CapabilityStoreDirConnectorOpenResponder)>

pub fn into_dictionary_create( self, ) -> Option<(u64, CapabilityStoreDictionaryCreateResponder)>

pub fn into_dictionary_legacy_import( self, ) -> Option<(u64, Channel, CapabilityStoreDictionaryLegacyImportResponder)>

pub fn into_dictionary_legacy_export( self, ) -> Option<(u64, Channel, CapabilityStoreDictionaryLegacyExportResponder)>

pub fn into_dictionary_insert( self, ) -> Option<(u64, DictionaryItem, CapabilityStoreDictionaryInsertResponder)>

pub fn into_dictionary_get( self, ) -> Option<(u64, String, u64, CapabilityStoreDictionaryGetResponder)>

pub fn into_dictionary_remove( self, ) -> Option<(u64, String, Option<Box<WrappedCapabilityId>>, CapabilityStoreDictionaryRemoveResponder)>

pub fn into_dictionary_copy( self, ) -> Option<(u64, u64, CapabilityStoreDictionaryCopyResponder)>

pub fn into_dictionary_keys( self, ) -> Option<(u64, ServerEnd<DictionaryKeysIteratorMarker>, CapabilityStoreDictionaryKeysResponder)>

pub fn into_dictionary_enumerate( self, ) -> Option<(u64, ServerEnd<DictionaryEnumerateIteratorMarker>, CapabilityStoreDictionaryEnumerateResponder)>

pub fn into_dictionary_drain( self, ) -> Option<(u64, Option<ServerEnd<DictionaryDrainIteratorMarker>>, CapabilityStoreDictionaryDrainResponder)>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for CapabilityStoreRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.