sdk/fidl/fuchsia.session/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.session;

using fuchsia.sys2;

/// 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.
    ProposeElement(ElementSpec spec) -> () error ProposeElementError;
};

/// 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.
    REJECTED = 2;
};

/// Describes an Element to be added to a session.
table ElementSpec {
    /// The component URL of the Element.
    1: string:fuchsia.sys2.MAX_URL_LENGTH component_url;
};