blob: 8b5dac70098565cb865afcf6f2fa533df316d863 [file] [log] [blame]
// 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.
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)
/// If `spec.arguments` is specified,
/// * `spec.component_url` must point to a CFv1 component
/// (`arguments` is not supported for CFv2 components)
/// + `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`]
/// if `spec.arguments`:
/// - is specified for a CFv2 `spec.component_url`
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;
/// Arguments provided to the component. Optional.
4: arguments vector<string:MAX>:MAX;
/// Errors that can be returned when attempting to add elements to a session.
type ProposeElementError = strict enum {
/// The element spec was malformed.
/// The element's component URL could not be resolved.
/// 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;