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 theannotations
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 addelement_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
ifspec.component_url
is missing or could not be resolved - error
ProposeElementError.REJECTED
ifspec.additional_services
is specified for a CFv2spec.component_url
- error
ProposeElementError.REJECTED
ifspec.additional_services
does not have a valid fuchsia.sys/ServiceList.host_directory - error
ProposeElementError.REJECTED
ifspec.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 presentview_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
ifconfiguration.session_url
is not set. - error
LaunchError.NOT_FOUND
ifconfiguration.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 malformedViewSpec
(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:
|
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 |
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 |
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 |
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 |
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. |
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
|