class CapabilityStore
Defined at line 12136 of file fidling/gen/sdk/fidl/fuchsia.component.sandbox/fuchsia.component.sandbox/hlcpp/fuchsia/component/sandbox/cpp/fidl.h
Protocol that represents the concept of a "capability store", a repository
for [Capability]s 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 [Capability]s. A [CapabilityStore] instance
contains a set of [Capability]s, 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 [CapabilityId]s, because
[CapabilityId]s 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.
Public Members
static const char[] Name_Public Methods
void ~CapabilityStore ()void Duplicate (uint64_t id, uint64_t dest_id, DuplicateCallback callback)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.
void Drop (uint64_t id, DropCallback callback)Drops the capability with `id` from this [`CapabilityStore`].
Errors:
- `ID_NOT_FOUND` if `id` was not a valid capability id in this store.
void Export (uint64_t id, ExportCallback callback)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.
void Import (uint64_t id, ::fuchsia::component::sandbox::Capability capability, ImportCallback callback)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].
void ConnectorCreate (uint64_t id, ::fidl::InterfaceHandle< ::fuchsia::component::sandbox::Receiver> receiver, ConnectorCreateCallback callback)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.
void ConnectorOpen (uint64_t id, ::zx::channel server_end, ConnectorOpenCallback callback)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.
void DirConnectorCreate (uint64_t id, ::fidl::InterfaceHandle< ::fuchsia::component::sandbox::DirReceiver> receiver, DirConnectorCreateCallback callback)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.
void DirConnectorOpen (::fuchsia::component::sandbox::CapabilityStoreDirConnectorOpenRequest CapabilityStoreDirConnectorOpenRequest, DirConnectorOpenCallback callback)Open a connection from the provided [DirConnector] capability that will
be dispatched to the [DirReceiver] on the other end. The `id` and
`server_end` arguments are required, and the `flags` and `path`
arguments are optional (a path of `.` will be used if one is not
otherwise set).
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.
void DictionaryCreate (uint64_t id, DictionaryCreateCallback callback)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.
void DictionaryLegacyImport (uint64_t id, ::zx::channel client_end, DictionaryLegacyImportCallback callback)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.
void DictionaryLegacyExport (uint64_t id, ::zx::channel server_end, DictionaryLegacyExportCallback callback)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.
void DictionaryInsert (uint64_t id, ::fuchsia::component::sandbox::DictionaryItem item, DictionaryInsertCallback callback)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`.
void DictionaryGet (uint64_t id, ::std::string key, uint64_t dest_id, DictionaryGetCallback callback)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.
void DictionaryRemove (uint64_t id, ::std::string key, ::std::unique_ptr< ::fuchsia::component::sandbox::WrappedCapabilityId> dest_id, DictionaryRemoveCallback callback)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.
void DictionaryCopy (uint64_t id, uint64_t dest_id, DictionaryCopyCallback callback)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.
void DictionaryKeys (uint64_t id, ::fidl::InterfaceRequest< ::fuchsia::component::sandbox::DictionaryKeysIterator> iterator, DictionaryKeysCallback callback)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.
void DictionaryEnumerate (uint64_t id, ::fidl::InterfaceRequest< ::fuchsia::component::sandbox::DictionaryEnumerateIterator> iterator, DictionaryEnumerateCallback callback)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.
void DictionaryDrain (uint64_t id, ::fidl::InterfaceRequest< ::fuchsia::component::sandbox::DictionaryDrainIterator> iterator, DictionaryDrainCallback callback)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.
void CreateServiceAggregate (::std::vector< ::fuchsia::component::sandbox::AggregateSource> sources, CreateServiceAggregateCallback callback)Creates a new DirConnector that forwards open requests to a set of
sources.
Protected Methods
void handle_unknown_method (uint64_t ordinal, bool method_has_response)Friends
class CapabilityStore_Stub