| // 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; |
| |
| @available(added=19) |
| const MANAGER_NAMESPACE string = "element_manager"; |
| |
| // The following annotation keys are all in the element manager namespace. |
| |
| /// The name of the element in its collection. If not provided to `ProposeElement`, a random name is |
| /// chosen. |
| @available(added=19) |
| const ANNOTATION_KEY_NAME string = "name"; |
| |
| /// If present, the element will persist over a reboot. |
| @available(added=19) |
| const ANNOTATION_KEY_PERSIST_ELEMENT string = "persist_element"; |
| |
| /// The component URL of the element. |
| @available(added=19) |
| const ANNOTATION_KEY_URL string = "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 (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()`. |
| @discoverable |
| closed 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 |
| /// + `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` could not be resolved |
| /// * error `ProposeElementError.INVALID_ARGS` if a required field is not present or annotations |
| /// are invalid |
| @available(replaced=19) |
| strict ProposeElement(resource struct { |
| spec Spec; |
| controller server_end:<Controller, optional>; |
| }) -> () error ProposeElementError; |
| @available(added=19) |
| strict ProposeElement(resource struct { |
| spec Spec; |
| controller server_end:<Controller, optional>; |
| }) -> () error ManagerError; |
| |
| /// 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. |
| @available(added=19) |
| strict RemoveElement(struct { |
| name string:MAX; |
| }) -> () error ManagerError; |
| }; |
| |
| /// 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. If the element |
| /// manager URL annotation is included (which is allowed, but not necessary), then it *must* |
| /// match `component_url`. |
| 2: annotations Annotations; |
| |
| @available(removed=12) |
| 3: additional_services fuchsia.sys.ServiceList; |
| |
| @available(removed=12) |
| 4: arguments vector<string:MAX>:MAX; |
| }; |
| |
| /// Errors that can be returned when using the Manager protocol. |
| @available(removed=19) |
| type ProposeElementError = strict enum { |
| /// The element spec was malformed. |
| INVALID_ARGS = 1; |
| |
| /// The element's component URL could not be resolved. |
| NOT_FOUND = 2; |
| }; |
| |
| @available(added=19) |
| type ManagerError = strict enum { |
| /// The element spec was malformed. |
| INVALID_ARGS = 1; |
| |
| /// The element's component URL could not be resolved. |
| NOT_FOUND = 2; |
| |
| /// Unable to persist a proposed element because there was an issue writing to persistent |
| /// storage. The proposed element will not have been started. |
| UNABLE_TO_PERSIST = 3; |
| }; |
| |
| /// 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. |
| closed protocol Controller { |
| compose AnnotationController; |
| }; |