PROTOCOLS
AnnotationController
Defined in fuchsia.element/annotations.fidl
An interface to create, read, update, and delete annotations, typically on an element or its view.
GetAnnotations
Returns the current Annotations
for the element.
- error
GetAnnotationsError
if the annotations could not be returned.
Request
<EMPTY>
Response
Name | Type |
---|---|
result |
AnnotationController_GetAnnotations_Result
|
UpdateAnnotations
Adds, updates, and removes annotations.
The server is expected to adhere to the following conventions:
- If a key in
annotations_to_set
is new, a new annotation is added - If a key in
annotations_to_set
already exists, the annotation value is updated - If a key in
annotations_to_delete
does not exist, it is ignored
The same key cannot appear twice in a call to UpdateAnnotations(). In other words, to set two Annotations with matching keys is illegal, as is an attempt to set an Annotation and also delete it.
If the operation results in an error, the annotations remain unchanged, and will not be partially updated.
- error
UpdateAnnotationsError.INVALID_ARGS
if the same key exists in bothannotations_to_set
andannotations_to_delete
. - error
UpdateAnnotationsError.INVALID_ARGS
if a key inannotations_to_set
orannotations_to_delete
has an empty namespace. - error
UpdateAnnotationsError.INVALID_ARGS
if anAnnotationValue.buffer
inannotations_to_set
could not be read. - error
UpdateAnnotationsError.TOO_MANY_ANNOTATIONS
if the operation results in more thanMAX_ANNOTATIONS_PER_ELEMENT
annotations existing.
Request
Name | Type |
---|---|
annotations_to_set |
Annotations
|
annotations_to_delete |
AnnotationKeys
|
Response
Name | Type |
---|---|
result |
AnnotationController_UpdateAnnotations_Result
|
WatchAnnotations
Returns the full set of Annotations
when one or more of them have changed, or
when this method is called by the client for the first time.
This operation does not block other requests from the client, but only one
WatchAnnotations
request at a time can be made on a connection. If the
client makes a second WatchAnnotations
request before waiting for the
previous request to complete, the connection will be closed.
- error
WatchAnnotationsError
if the annotations could not be returned.
Request
<EMPTY>
Response
Name | Type |
---|---|
result |
AnnotationController_WatchAnnotations_Result
|
Controller
Defined in fuchsia.element/element_manager.fidl
An interface that gives clients of Manager
(element proposers) control
over the proposed element's lifecycle and annotations.
Lifecycle
The client must keep Controller
connected to ensure the element
remains in the session and is not destroyed. Once Controller
is closed,
the element and its component will be terminated. The element may also terminate
itself, which will cause Controller
to close.
GetAnnotations
Returns the current Annotations
for the element.
- error
GetAnnotationsError
if the annotations could not be returned.
Request
<EMPTY>
Response
Name | Type |
---|---|
result |
AnnotationController_GetAnnotations_Result
|
UpdateAnnotations
Adds, updates, and removes annotations.
The server is expected to adhere to the following conventions:
- If a key in
annotations_to_set
is new, a new annotation is added - If a key in
annotations_to_set
already exists, the annotation value is updated - If a key in
annotations_to_delete
does not exist, it is ignored
The same key cannot appear twice in a call to UpdateAnnotations(). In other words, to set two Annotations with matching keys is illegal, as is an attempt to set an Annotation and also delete it.
If the operation results in an error, the annotations remain unchanged, and will not be partially updated.
- error
UpdateAnnotationsError.INVALID_ARGS
if the same key exists in bothannotations_to_set
andannotations_to_delete
. - error
UpdateAnnotationsError.INVALID_ARGS
if a key inannotations_to_set
orannotations_to_delete
has an empty namespace. - error
UpdateAnnotationsError.INVALID_ARGS
if anAnnotationValue.buffer
inannotations_to_set
could not be read. - error
UpdateAnnotationsError.TOO_MANY_ANNOTATIONS
if the operation results in more thanMAX_ANNOTATIONS_PER_ELEMENT
annotations existing.
Request
Name | Type |
---|---|
annotations_to_set |
Annotations
|
annotations_to_delete |
AnnotationKeys
|
Response
Name | Type |
---|---|
result |
AnnotationController_UpdateAnnotations_Result
|
WatchAnnotations
Returns the full set of Annotations
when one or more of them have changed, or
when this method is called by the client for the first time.
This operation does not block other requests from the client, but only one
WatchAnnotations
request at a time can be made on a connection. If the
client makes a second WatchAnnotations
request before waiting for the
previous request to complete, the connection will be closed.
- error
WatchAnnotationsError
if the annotations could not be returned.
Request
<EMPTY>
Response
Name | Type |
---|---|
result |
AnnotationController_WatchAnnotations_Result
|
GraphicalPresenter
Defined in fuchsia.element/graphical_presenter.fidl
An interface used to present graphical views.
The GraphicalPresenter
protocol is typically implemented by a session component or
its child that presents element views.
The presented views can be annotated with fuchsia.element.Annotations
to communicate
presentation properties to the GraphicalPresenter
.
PresentView
Presents the view described by view_spec
.
ViewController
view_controller
allows clients to receive a ViewController
for the
presented view. The client can use the ViewController
to control the view's
presentation and receive events.
If view_controller
is closed, the client can assume that the view is
no longer being presented, and will not be presented in the future.
If the client closes the view_controller
, or does not provide a request
to PresentView
, the view may be dismissed at any time with no signal to the client.
Errors
PresentView
errors are signaled by closing view_controller
with an epitaph, ViewControllerEpitaph
. See ViewController.
view_spec
describes the view to presentannotation_controller
a handle to make changes to the respective element's annotationsview_controller_request
an optional request for a controller for the view
- error
view_spec
must containview_holder_token
andview_ref
for Gfx views, ORviewport_creation_token
for Flatland views, but never both. If both are set, errorPresentViewError.INVALID_ARGS
is thrown. - error
PresentViewError.INVALID_ARGS
ifspec.view_holder_token
orspec.view_ref
are missing or invalid - error
PresentViewError
if the view could not be presented
Request
Name | Type |
---|---|
view_spec |
ViewSpec
|
annotation_controller |
AnnotationController?
|
view_controller_request |
server_end<ViewController>?
|
Response
Name | Type |
---|---|
result |
GraphicalPresenter_PresentView_Result
|
Manager
Defined in fuchsia.element/element_manager.fidl
An interface used to add elements to a session.
An element is a component that is expected to be instantiated as a child
of the session and to interact with the user in some way. An element proposer
is a component that calls ProposeElement
to add an element to the session.
The session will typically implement Manager
and provide it
to its child element proposers.
For example, an element proposer may be a non-interactive application that
listens to the network for a command to display an element to the user.
When it receives the command, the element proposer proposes to add an
element to the session via the Manager
protocol. Similarly,
the element proposer may be part of an interactive user interface that
proposes elements based on user input.
ProposeElement
Proposes to add an element to the session.
If ProposeElement
returns without error, the caller can assume
the element is now part of the session. However, whether or not the
element component is actively running, or not, depends on the session
implementation. For example, a session may decide to conserve resources by
suspending an element which is not visible, or delay the running of an
element until a more appropriate time.
Spec
spec.component_url
is required
If spec.additional_services
is specified,
-
spec.component_url
must point to a CFv1 component (additional_services
is not supported for CFv2 components) -
The fuchsia.sys/ServiceList.host_directory field in
spec.additional_services
must be set to a channel to a directory hosting the services (fuchsia.sys/ServiceList.provider is not supported and must be null)
If spec.arguments
is specified,
spec.component_url
must point to a CFv1 component (arguments
is not supported for CFv2 components)
spec
describes the element to addcontroller
can be used to observe and affect the lifecycle of the element, and to set and get annotations on the element
- error
ProposeElementError.NOT_FOUND
ifspec.component_url
is missing or could not be resolved - error
ProposeElementError.INVALID_ARGS
ifspec.additional_services
:- is specified for a CFv2
spec.component_url
, or - does not have a valid fuchsia.sys/ServiceList.host_directory, or
- contains a non-null fuchsia.sys/ServiceList.provider
if
spec.arguments
: - is specified for a CFv2
spec.component_url
- is specified for a CFv2
Request
Name | Type |
---|---|
spec |
Spec
|
controller |
server_end<Controller>?
|
Response
Name | Type |
---|---|
result |
Manager_ProposeElement_Result
|
ViewController
Defined in fuchsia.element/graphical_presenter.fidl
An interface that gives clients of GraphicalPresenter
control over a view
that was presented.
Lifecycle
The client must keep ViewController
connected to ensure the view is
presented. Once ViewController
is closed, the view will be
permanently dismissed.
For example, if the view originates from an element, the component
that manages the element's lifecycle may choose to stop the element's
component once the ViewController
is closed.
Epitaph
This protocol is closed with an epitaph:
ZX_OK
when the view is dismissed
Dismiss
Instructs the presenter to dismiss the associated view.
This call results in the ViewController
being closed with a
ZX_OK
epitaph once any exit animation has been performed, the
view/view holder connection has been severed, and the component
instance serving the view can be terminated.
Request
<EMPTY>
OnPresented
Informs the view controller that the view was presented successfully.
Response
<EMPTY>
STRUCTS
Annotation resource
Defined in fuchsia.element/annotations.fidl
An annotation defined dynamically by key/value pair.
The Session Framework does not constrain the contents of key
and value
in any way. Cooperating components that exchange annotations must define
and validate annotation entries based on their own conventions.
Field | Type | Description | Default |
---|---|---|---|
key |
AnnotationKey
|
An identfier for this annotation. |
No default |
value |
AnnotationValue
|
The content of this annotation. |
No default |
AnnotationController_GetAnnotations_Response resource
Defined in fuchsia.element/annotations.fidl
Field | Type | Description | Default |
---|---|---|---|
annotations |
Annotations
|
No default |
AnnotationController_UpdateAnnotations_Response
Defined in fuchsia.element/annotations.fidl
<EMPTY>
AnnotationController_WatchAnnotations_Response resource
Defined in fuchsia.element/annotations.fidl
Field | Type | Description | Default |
---|---|---|---|
annotations |
Annotations
|
No default |
AnnotationKey
Defined in fuchsia.element/annotations.fidl
The key of an fuchsia.element/Annotation.
Field | Type | Description | Default |
---|---|---|---|
namespace |
string[128]
|
A namespace that disambiguates groups of keys across clients. This is intended to group related keys together under the same identifier, and avoid naming collisions. For example, a session may use a custom namespace to define annotations that are specific to its implementation. The namespace is required and must be non-empty. The namespace "global" is represents the global namespace, reserved for annotations common across many products and session components. To ensure compatibility, clients should use a unique namespace, like a UUID or the client's component URL, when introducing new keys. |
No default |
value |
string[128]
|
An identifier for this annotation, uniquely identifying the annotation
within |
No default |
GraphicalPresenter_PresentView_Response
Defined in fuchsia.element/graphical_presenter.fidl
<EMPTY>
Manager_ProposeElement_Response
Defined in fuchsia.element/element_manager.fidl
<EMPTY>
ENUMS
GetAnnotationsError strict
Type: uint32
Defined in fuchsia.element/annotations.fidl
An error returned from ElementController/GetAnnotations
.
Name | Value | Description |
---|---|---|
BUFFER_READ_FAILED |
1 |
The |
PresentViewError strict
Type: uint32
Defined in fuchsia.element/graphical_presenter.fidl
An error returned when GraphicalPresenter
fails to present a view.
Name | Value | Description |
---|---|---|
INVALID_ARGS |
1 |
The provided |
ProposeElementError strict
Type: uint32
Defined in fuchsia.element/element_manager.fidl
Errors that can be returned when attempting to add elements to a session.
Name | Value | Description |
---|---|---|
INVALID_ARGS |
1 |
The element spec was malformed. |
NOT_FOUND |
2 |
The element's component URL could not be resolved. |
UpdateAnnotationsError strict
Type: uint32
Defined in fuchsia.element/annotations.fidl
An error returned from AnnotationController/UpdateAnnotations
Name | Value | Description |
---|---|---|
INVALID_ARGS |
1 |
The arguments passed to |
TOO_MANY_ANNOTATIONS |
2 |
The total number of annotations will exceed MAX_ANNOTATIONS_PER_ELEMENT as a result of updating the annotations. |
WatchAnnotationsError flexible
Type: uint32
Defined in fuchsia.element/annotations.fidl
An error returned from AnnotationController/WatchAnnotations
and
ElementController/WatchAnnotations
.
Name | Value | Description |
---|---|---|
BUFFER_READ_FAILED |
1 |
The |
TABLES
Spec resource
Defined in fuchsia.element/element_manager.fidl
Description of an element to be added to a session.
Ordinal | Field | Type | Description |
---|---|---|---|
1 |
component_url |
fuchsia.url/Url
|
The component URL of the element. Required. |
2 |
annotations |
Annotations
|
Initial annotations on the element. Required, but can be an empty vector. |
3 |
additional_services |
fuchsia.sys/ServiceList
|
A list of services passed to the Element. Optional. |
4 |
arguments |
vector<string>
|
Arguments provided to the component. Optional. |
ViewSpec resource
Defined in fuchsia.element/graphical_presenter.fidl
A description of a view that can be presented by a GraphicalPresenter
.
Ordinal | Field | Type | Description |
---|---|---|---|
1 |
view_holder_token |
fuchsia.ui.views/ViewHolderToken
|
The view holder token for the presented Gfx view. Must be unset for Flatland views. |
2 |
view_ref |
fuchsia.ui.views/ViewRef
|
The |
3 |
annotations |
Annotations
|
The annotations associated with the presented view. The presenter must observe incoming annotations and update the presentation accordingly. For views that come from elements, the annotations are expected to be the same
as the annotations for the element. For example, if the Optional. |
4 |
viewport_creation_token |
fuchsia.ui.views/ViewportCreationToken
|
The viewport creation token for the presented Flatland view. Must be unset for Gfx views. |
UNIONS
AnnotationController_GetAnnotations_Result strict resource
Defined in fuchsia.element/annotations.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
AnnotationController_GetAnnotations_Response
|
|
2 |
err |
GetAnnotationsError
|
AnnotationController_UpdateAnnotations_Result strict
Defined in fuchsia.element/annotations.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
AnnotationController_UpdateAnnotations_Response
|
|
2 |
err |
UpdateAnnotationsError
|
AnnotationController_WatchAnnotations_Result strict resource
Defined in fuchsia.element/annotations.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
AnnotationController_WatchAnnotations_Response
|
|
2 |
err |
WatchAnnotationsError
|
AnnotationValue strict resource
Defined in fuchsia.element/annotations.fidl
The value of an fuchsia.element/Annotation.
The actual field used depends on the type of annotation.
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
text |
string
|
|
2 |
buffer |
fuchsia.mem/Buffer
|
GraphicalPresenter_PresentView_Result strict
Defined in fuchsia.element/graphical_presenter.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
GraphicalPresenter_PresentView_Response
|
|
2 |
err |
PresentViewError
|
Manager_ProposeElement_Result strict
Defined in fuchsia.element/element_manager.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
Manager_ProposeElement_Response
|
|
2 |
err |
ProposeElementError
|
CONSTANTS
Name | Value | Type | Description |
---|---|---|---|
MAX_ANNOTATIONS_PER_ELEMENT |
1024
|
uint32 |
Maximum number of annotations for a single element or view. |
MAX_ANNOTATION_KEY_NAMESPACE_SIZE |
128
|
uint32 |
Maximum length of |
MAX_ANNOTATION_KEY_VALUE_SIZE |
128
|
uint32 |
Maximum length of |
ALIASES
Name | Value | Description |
---|---|---|
AnnotationKeys |
vector [MAX_ANNOTATIONS_PER_ELEMENT ] |
A list of annotation keys. |
Annotations |
vector [MAX_ANNOTATIONS_PER_ELEMENT ] |
A list of annotations on an element. |