fuchsia.element

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
payload	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 both annotations_to_set and annotations_to_delete.
• error UpdateAnnotationsError.INVALID_ARGS if a key in annotations_to_set or annotations_to_delete has an empty namespace.
• error UpdateAnnotationsError.INVALID_ARGS if an AnnotationValue.buffer in annotations_to_set could not be read.
• error UpdateAnnotationsError.TOO_MANY_ANNOTATIONS if the operation results in more than MAX_ANNOTATIONS_PER_ELEMENT annotations existing.

Request

Name	Type
annotations_to_set	Annotations
annotations_to_delete	AnnotationKeys

Response

Name	Type
payload	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
payload	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
payload	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 both annotations_to_set and annotations_to_delete.
• error UpdateAnnotationsError.INVALID_ARGS if a key in annotations_to_set or annotations_to_delete has an empty namespace.
• error UpdateAnnotationsError.INVALID_ARGS if an AnnotationValue.buffer in annotations_to_set could not be read.
• error UpdateAnnotationsError.TOO_MANY_ANNOTATIONS if the operation results in more than MAX_ANNOTATIONS_PER_ELEMENT annotations existing.

Request

Name	Type
annotations_to_set	Annotations
annotations_to_delete	AnnotationKeys

Response

Name	Type
payload	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
payload	AnnotationController_WatchAnnotations_Result

GraphicalPresenter

Defined in fuchsia.element/graphical_presenter.fidl

An interface used to instruct a server to present graphical views, and observe and control the view's lifecycle.

PresentView

Presents the view described by view_spec.

If view_controller_request is provided, it will be connected to a ViewController implemented by the GraphicalPresenter server. When the view is dismissed, the ViewController channel is closed with a ZX_OK, at which point it is safe to clean up resources backing the view. To dismiss the view, the client should call ViewController.Dismiss() and wait for the ZX_OK epitaph. Not providing a view_controller_request handle will make it impossible for the client to observe the view's lifecycle.

• view_spec describes the view to present
• annotation_controller a handle to an AnnotationController, allowing the GraphicalPresenter server to observe and update the view's annotations.
• view_controller_request an optional request for a controller for the view

• error view_spec must contain view_holder_token and view_ref for Gfx views, OR viewport_creation_token for Flatland views, but never both. If both are set, error PresentViewError.INVALID_ARGS is returned.
• error PresentViewError.INVALID_ARGS if spec.view_holder_token or spec.view_ref are missing or invalid.

Request

Name	Type
view_spec	ViewSpec
annotation_controller	client_end:AnnotationController?
view_controller_request	server_end:ViewController?

Response

Name	Type
payload	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 (optionally) to interact with the user in some way.

The session will typically implement Manager and route it where needed. For tools like ffx session add to work, the session must expose Manager to its parent.

For example, a component in the session 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 component calls ProposeElement().

ProposeElement

Request

Name	Type
spec	Spec
controller	server_end:Controller?

Response

Name	Type
payload	Manager_ProposeElement_Result

RemoveElement

Removes the element identified by name from the session. If the element is a persistent element, it is removed permanently. Any persistent storage that the element might have used is left untouched.

Request

Name	Type
name	string

Response

Name	Type
payload	Manager_RemoveElement_Result

ViewController

Defined in fuchsia.element/graphical_presenter.fidl

Gives clients of GraphicalPresenter control over an individual view presented through PresentView().

Dismiss

Instructs the presenter to dismiss the associated view. Once dismissed, the ViewController channel is closed with a ZX_OK epitaph. At this point, it is safe to clean up any resources (such as terminating a component) backing the view.

Clients should call Dismiss() prior to closing the ViewController channel themselves.

Request

<EMPTY>

OnPresented

An event that signals that the view is now being presented.

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 namespace.	No default

GraphicalPresenter_PresentView_Response

Defined in fuchsia.element/graphical_presenter.fidl

<EMPTY>

Manager_ProposeElement_Response

Defined in fuchsia.element/element_manager.fidl

<EMPTY>

Manager_RemoveElement_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 AnnotationValue.buffer of an annotation could not be read.

ManagerError strict

Type: uint32

Defined in fuchsia.element/element_manager.fidl

Name	Value	Description
INVALID_ARGS	1	The element spec was malformed.
NOT_FOUND	2	The element's component URL could not be resolved.
UNABLE_TO_PERSIST	3	Unable to persist a proposed element because there was an issue writing to persistent storage. The proposed element will not have been started.

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 ViewSpec is invalid.

ProposeElementError strict

Type: uint32

Defined in fuchsia.element/element_manager.fidl

Errors that can be returned when using the Manager protocol.

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 UpdateAnnotations are malformed.
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 AnnotationValue.buffer of an annotation could not be read.

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. If the element manager URL annotation is included (which is allowed, but not necessary), then it must match component_url.

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. One of view_holder_token or viewport_creation_token must be set.
2	view_ref	fuchsia.ui.views/ViewRef	The ViewRef of the presented Gfx view. Must be unset for Flatland views.
3	annotations	Annotations	The initial annotations associated with the presented view. Updates to annotations are observed through the AnnotationController passed to PresentView(). Optional.
4	viewport_creation_token	fuchsia.ui.views/ViewportCreationToken	The viewport creation token for the presented Flatland view. Must be unset for Gfx views. One of view_holder_token or viewport_creation_token must be set.

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	ManagerError

Manager_RemoveElement_Result strict

Defined in fuchsia.element/element_manager.fidl

Ordinal	Variant	Type	Description
1	response	Manager_RemoveElement_Response
2	err	ManagerError

CONSTANTS

Name	Value	Type	Description
ANNOTATION_KEY_NAME	name	String	The name of the element in its collection. If not provided to ProposeElement, a random name is chosen. Added: 19
ANNOTATION_KEY_PERSIST_ELEMENT	persist_element	String	If present, the element will persist over a reboot. Added: 19
ANNOTATION_KEY_URL	url	String	The component URL of the element. Added: 19
MANAGER_NAMESPACE	element_manager	String	Added: 19
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 AnnotationKey.namespace.
MAX_ANNOTATION_KEY_VALUE_SIZE	128	uint32	Maximum length of AnnotationKey.value.

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.