fuchsia.session

PROTOCOLS

ElementController

Defined in fuchsia.session/element_manager.fidl

An interface that gives clients of ElementManager (element proposers) control over the proposed element's lifecycle and annotations.

Lifecycle

The client must keep ElementController connected to ensure the element remains in the session and is not destroyed. Once ElementController is closed, the element and its component will be terminated. The element may also terminate itself, which will cause ElementController to close.

GetAnnotations

Returns the current Annotations for the element.

• error AnnotationError.NOT_FOUND if the annotations could not be read.

Request

Name	Type

Response

Name	Type
result	ElementController_GetAnnotations_Result

SetAnnotations

Adds, updates, or removes annotations on the element.

When annotations.custom_annotations is specified, the server is expected to adhere to the following conventions:

• If a key is new, a new annotation is added

• If a key already exists and the value is not null, the annotation value is updated

• If a key already exists and the value is null, the annotation is deleted

• error AnnotationError.REJECTED if the annotations could not be set (the exact reason depends on the session implementation; see AnnotationError.REJECTED for some specific examples)

Request

Name	Type
annotations	Annotations

Response

Name	Type
result	ElementController_SetAnnotations_Result

ElementManager

Defined in fuchsia.session/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 ElementManager 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 ElementManager 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.

ElementSpec

• 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)

• spec describes the element to add
• element_controller 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 if spec.component_url is missing or could not be resolved
• error ProposeElementError.REJECTED if spec.additional_services is specified for a CFv2 spec.component_url
• error ProposeElementError.REJECTED if spec.additional_services does not have a valid fuchsia.sys/ServiceList.host_directory
• error ProposeElementError.REJECTED if spec.additional_services contains a non-null fuchsia.sys/ServiceList.provider

Request

Name	Type
spec	ElementSpec
element_controller	request<ElementController>?

Response

Name	Type
result	ElementManager_ProposeElement_Result

GraphicalPresenter

Defined in fuchsia.session/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.session.Annotations to communicate presentation properties to the GraphicalPresenter.

PresentView

Presents the view described by view_spec.

ViewSpec

view_spec.view_holder_token and view_spec.view_ref must be valid, otherwise PresentView will fail with ViewControllerEpitaph.INVALID_VIEW_SPEC.

ViewController

view_controller_request 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_request 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_request, 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_request with an epitaph, ViewControllerEpitaph. See ViewController.

• view_spec describes the view to present
• view_controller_request an optional request for a controller for the view

Request

Name	Type
view_spec	ViewSpec
view_controller_request	request<ViewController>?

Launcher

Defined in fuchsia.session/launcher.fidl

A protocol used to launch sessions.

Launch

Launches the session detailed in configuration.

If a session is currently running, the component associated with the running session will be destroyed.

• configuration describes the session to launch.

• error LaunchError.INVALID_ARGS if configuration.session_url is not set.
• error LaunchError.NOT_FOUND if configuration.session_url could not be resolved.
• error LaunchError.DESTROY_COMPONENT_FAILED if an existing session component could not be destroyed. The existing session remains running at this point.
• error LaunchError.CREATE_COMPONENT_FAILED if the session component could not be started. No session will be running at this point.

Request

Name	Type
configuration	LaunchConfiguration

Response

Name	Type
result	Launcher_Launch_Result

Restarter

Defined in fuchsia.session/launcher.fidl

A protocol used to restart the currently running session.

Restart

Restarts the session.

• error RestartError.NOT_RUNNING if there is no currently running session to restart.
• error RestartError.DESTROY_COMPONENT_FAILED if an existing session component could not be destroyed. The existing session remains running at this point.
• error RestartError.CREATE_COMPONENT_FAILED if the session component could not be started. No session will be running at this point.

Request

Name	Type

Response

Name	Type
result	Restarter_Restart_Result

ViewController

Defined in fuchsia.session/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:

• ViewControllerEpitaph.INVALID_VIEW_SPEC if the view failed to be presented because of a malformed ViewSpec (see GraphicalPresenter.PresentView)
• ViewControllerEpitaph.REJECTED if the presenter rejected the request to present the view (see GraphicalPresenter.PresentView)
• ViewControllerEpitaph.ZX_OK when the view is dismissed

Annotate

Annotates the view with annotations.

The presenter must observe incoming annotation requests and update the presentation accordingly.

The presenter must adhere to the following rules for annotation updates:

• Annotations are added when their Annotation.key was not present in a previous set of annotations
• Annotations are updated when their Annotation.value is non-null
• Annotations are deleted when their Annotation.value is null

When the Annotate call returns, clients can assume that annotations have been updated and incorporated into the presentation.

Request

Name	Type
annotations	Annotations

Response

Name	Type

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

Name	Type

OnPresented

Informs the view controller that the view was presented successfully.

Response

Name	Type

STRUCTS

Annotation

Defined in fuchsia.session/annotation.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.

Name	Type	Description	Default
key	string	An identfier for this annotation.	No default
value	Value?	The content of this annotation.	No default

ElementController_GetAnnotations_Response

Defined in fuchsia.session/element_manager.fidl

Name	Type	Description	Default
annotations	Annotations		No default

ElementController_SetAnnotations_Response

Defined in fuchsia.session/element_manager.fidl

Name	Type	Description	Default

ElementManager_ProposeElement_Response

Defined in fuchsia.session/element_manager.fidl

Name	Type	Description	Default

Launcher_Launch_Response

Defined in fuchsia.session/launcher.fidl

Name	Type	Description	Default

Restarter_Restart_Response

Defined in fuchsia.session/launcher.fidl

Name	Type	Description	Default

ENUMS

AnnotationError

Type: uint32

Defined in fuchsia.session/annotation.fidl

Error returned from methods that operate on annotations.

Name	Value	Description
REJECTED	1	The session rejected the provided annotations. Reasons for rejection may be due to annotations that violate defined type constraints, such as: The Value size exceeds the maximum length The total number of annotations on an element exceeds MAX
NOT_FOUND	2	The annotations on an element could not be returned. Reasons for this failure may be due to inability to read buffer bytes.

LaunchError

Type: uint32

Defined in fuchsia.session/launcher.fidl

An error that occurs when launching a session.

Name	Value	Description
INVALID_ARGS	1	The session's LaunchConfiguration is malformed.
NOT_FOUND	2	There was an error resolving the session's component URL.
DESTROY_COMPONENT_FAILED	3	The session component could not be destroyed.
CREATE_COMPONENT_FAILED	4	The session component could not be created.

ProposeElementError

Type: uint32

Defined in fuchsia.session/element_manager.fidl

Errors that can be returned when attempting to add elements to a session.

Name	Value	Description
NOT_FOUND	1	The element's component URL could not be resolved.
REJECTED	2	The session rejected the proposal to add the element. This may be because of a malformed ElementSpec.

RestartError

Type: uint32

Defined in fuchsia.session/launcher.fidl

An error that occurs when restarting a session.

Name	Value	Description
NOT_RUNNING	1	There is no currently running session to restart.
NOT_FOUND	2	There was an error resolving the session's component URL.
DESTROY_COMPONENT_FAILED	3	The session component could not be destroyed.
CREATE_COMPONENT_FAILED	4	The session component could not be created.

ViewControllerEpitaph

Type: uint32

Defined in fuchsia.session/graphical_presenter.fidl

Epitaph returned when ViewController is closed to signal an error.

Name	Value	Description
INVALID_VIEW_SPEC	1	The provided ViewSpec was missing a valid ViewHolderToken.
REJECTED	2	The presenter rejected the request to present the view.

TABLES

Annotations

Defined in fuchsia.session/annotation.fidl

The annotations applied to an element.

Ordinal	Name	Type	Description
1	custom_annotations	vector<Annotation>	A list of dynamically-defined annotations.

ElementSpec

Defined in fuchsia.session/element_manager.fidl

Description of an element to be added to a session.

Ordinal	Name	Type	Description
1	component_url	fuchsia.url/Url	The component URL of the element. Required.
2	annotations	Annotations	Initial annotations on the element. Optional.
3	additional_services	fuchsia.sys/ServiceList	A list of services passed to the Element. Optional.

LaunchConfiguration

Defined in fuchsia.session/launcher.fidl

Describes a session to launch.

Ordinal	Name	Type	Description
1	session_url	string[4096]	The component URL of the session.

ViewSpec

Defined in fuchsia.session/graphical_presenter.fidl

A description of a view that can be presented by a GraphicalPresenter.

Ordinal	Name	Type	Description
1	view_holder_token	fuchsia.ui.views/ViewHolderToken	The view holder token for the presented view.
2	view_ref	fuchsia.ui.views/ViewRef	The ViewRef of the presented view.
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 GraphicalPresenter component uses ElementManager to add an element to the session, and gives it an annotation, the presenter can expect that annotation to be passed back in ViewSpec.annotations for the associated view. Optional.

UNIONS

ElementController_GetAnnotations_Result

Defined in fuchsia.session/element_manager.fidl

Name	Type	Description
response	ElementController_GetAnnotations_Response
err	AnnotationError

ElementController_SetAnnotations_Result

Defined in fuchsia.session/element_manager.fidl

Name	Type	Description
response	ElementController_SetAnnotations_Response
err	AnnotationError

ElementManager_ProposeElement_Result

Defined in fuchsia.session/element_manager.fidl

Name	Type	Description
response	ElementManager_ProposeElement_Response
err	ProposeElementError

Launcher_Launch_Result

Defined in fuchsia.session/launcher.fidl

Name	Type	Description
response	Launcher_Launch_Response
err	LaunchError

Restarter_Restart_Result

Defined in fuchsia.session/launcher.fidl

Name	Type	Description
response	Restarter_Restart_Response
err	RestartError

Value

Defined in fuchsia.session/annotation.fidl

The value of an Annotation.

The actual field used depends on the type of annotation.

Name	Type	Description
text	string
buffer	fuchsia.mem/Buffer