| // 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.session; |
| |
| using fuchsia.io; |
| using fuchsia.io2; |
| using fuchsia.url; |
| |
| /// The ElementManager is responsible for service requests to add elements to a |
| /// session. |
| /// |
| /// An Element is a component which is expected to be instantiated as a child |
| /// of the session and interact with the user in some way. |
| /// |
| /// For example, a component acting as an element proposer may be listening to |
| /// the network for instructions to display an element to the user. When such |
| /// a network command is received, the element proposer proposes to add an |
| /// element to the session via the `ElementManager` protocol. |
| [Discoverable] |
| protocol ElementManager { |
| /// 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, is left to the session's |
| /// discretion. For example, a session may decide to conserve resources by |
| /// suspending an element which is not in focus, or delay the running of an |
| /// element until a more appropriate time. |
| /// |
| /// `spec` describes the Element to add. |
| /// `element_controller` can be used to set and get annotations on the Element |
| /// created by the `ElementManager`. |
| ProposeElement(ElementSpec spec, request<ElementController>? element_controller) |
| -> () error ProposeElementError; |
| }; |
| |
| protocol ElementController { |
| /// 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, the annotation is updated. |
| /// * If a key exists with a null value, the annotation is deleted. |
| SetAnnotations(Annotations annotations) -> () error AnnotationError; |
| |
| /// Returns the current `Annotations` for the controlled element. |
| GetAnnotations() -> (Annotations annotations) error AnnotationError; |
| }; |
| |
| /// Errors which can be returned when attempting to add elements to a session. |
| enum ProposeElementError { |
| /// There was an error resolving the element's component url. |
| NOT_FOUND = 1; |
| |
| /// The session rejected the proposal to add the element. Reasons may include |
| /// errors with components of the ElementSpec. (See `AnnotationError` for |
| /// some specific examples.) |
| REJECTED = 2; |
| }; |
| |
| /// Describes an Element to be added to a session. |
| table ElementSpec { |
| /// The component URL of the Element. |
| 1: fuchsia.url.Url component_url; |
| |
| /// Initial metadata on the element. Optional. |
| 2: Annotations annotations; |
| |
| // TODO(fxb/44648): Remove this field after converting all components to Component Framework v2, |
| // unless the concept of providing services in this way has been approved for dynamically-routed |
| // v2->v2 interactions. |
| /// Requests the Element Manager forward the given capabilities to the component at launch. |
| /// The Element Manager should forward these capabilities to the relevant Runner, and the |
| /// Runner should expose these capabilities to the launched component's incoming namespace. |
| /// (This mechanism allows backward compatibility for Runners to launch v1 (`.cmx`) components |
| /// that require additional services.) |
| 3: AdditionalCapabilities additional_capabilities; |
| }; |
| |
| // TODO(fxb/44648): Remove this field after converting all components to Component Framework v2, |
| // unless the concept of providing services in this way has been approved for dynamically-routed |
| // v2->v2 interactions. |
| /// Provides a list of capabilities to be offered to a proposed element, and a Directory from which |
| /// another component can connect to the implementations of those capabilities. |
| struct AdditionalCapabilities { |
| /// A list of capabilities by absolute path name, relative to the given host_directory (for |
| /// example, "/svc/fuchsia.util.SomeService"). |
| vector<fuchsia.io2.Path>:MAX paths; |
| |
| /// The `Directory` from which the capabilities are served. |
| fuchsia.io.Directory host_directory; |
| }; |