sdk/fidl/fuchsia.element/element_manager.fidl

// 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.
///
/// 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
    strict ProposeElement(resource struct {
        spec Spec;
        controller server_end:<Controller, optional>;
    }) -> () 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;

    @available(removed=12)
    3: additional_services fuchsia.sys.ServiceList;
    @available(added=12)
    3: reserved;

    @available(removed=12)
    4: arguments vector<string:MAX>:MAX;
    @available(added=12)
    4: reserved;
};

/// 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.
closed protocol Controller {
    compose AnnotationController;
};