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.url;
using fuchsia.data;

/// Describes the annotations which is metadata that describes an element.
table Annotations {
    /// The user-defined annotations.
    1: fuchsia.data.Dictionary custom_annotations;
};

/// 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);
};

/// 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;
};

/// Error returned from calls to SetAnnotations().
enum AnnotationError {
    /// The session rejected the annotations to add to the controlled element.
    REJECTED = 1;
};

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

    /// Initial `Annotations` on the element. Optional.
    2: Annotations annotations;
};