| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.element; |
| |
| using fuchsia.sys; |
| using fuchsia.url; |
| |
| /// 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. |
| @discoverable |
| protocol Manager { |
| /// 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) |
| /// |
| /// + `spec` describes the element to add |
| /// + `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.INVALID_ARGS` |
| /// if `spec.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`] |
| ProposeElement(resource struct { |
| spec Spec; |
| controller server_end:<Controller, optional>; |
| }) -> (struct {}) error ProposeElementError; |
| }; |
| |
| /// Description of an element to be added to a session. |
| type Spec = resource table { |
| /// The component URL of the element. Required. |
| 1: component_url fuchsia.url.Url; |
| |
| /// Initial annotations on the element. Required, but can be an empty vector. |
| 2: annotations Annotations; |
| |
| /// A list of services passed to the Element. Optional. |
| 3: additional_services fuchsia.sys.ServiceList; |
| }; |
| |
| /// Errors that can be returned when attempting to add elements to a session. |
| type ProposeElementError = strict enum { |
| /// The element spec was malformed. |
| INVALID_ARGS = 1; |
| |
| /// The element's component URL could not be resolved. |
| NOT_FOUND = 2; |
| }; |
| |
| /// 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. |
| protocol Controller { |
| compose AnnotationController; |
| }; |