sdk/fidl/fuchsia.media.sessions/service.fidl

// Copyright 2018 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.media.sessions;

/// `Publisher` publishes media sessions. This allows priviledged processes to
/// send media controls to the media session and observe changes in its
/// playback state.
[Discoverable]
protocol Publisher {
    /// Publishes a session. Returns `session_id` which can be used to
    /// to identify the session.
    Publish(Session session) -> (handle<event> session_id);
    /// Publishes a remote session, whose playback does not originate on this
    /// device. Returns a `session_id` which can be used to identify the session.
    PublishRemote(Session session) -> (handle<event> session_id);
};

/// Describes the session which is currently implementing the active session
/// interface.
table ActiveSession {
    1: handle<event> session_id;
};

/// A registered session in the Media Session registry.
table SessionEntry {
    /// The id of the registered session.
    1: handle<event> session_id;
    /// Whether the session takes place locally on this device.
    2: bool local;
};

enum SessionDelta {
    ADDED = 0;
    REMOVED = 1;
};

/// A change to the set of registered sessions.
struct SessionsChange {
    SessionEntry session;
    SessionDelta delta;
};

/// `Registry` observes the collection of published media sessions
/// and vends control handles to them.
[Discoverable]
protocol Registry {
    /// `OnActiveSessionChanged` is sent on connection and when the
    /// underlying active session is changed.
    -> OnActiveSessionChanged(ActiveSession active_session);

    /// Notifies the `Registry` that the active session change events was handled
    /// and that the client is ready for more. If you want these events, send
    /// this message on receipt of them. After some amount of events are sent
    /// without receipts, the client will stop receiving events from the
    /// `Registry`.
    ///
    /// Never sending this message has no effect other than unsubscribing from
    /// these events.
    NotifyActiveSessionChangeHandled();

    /// When the set of registered sessions changes, this event is sent. On
    /// connection the client is caught up to the state of the collection with
    /// "ADD" events for each existing session.
    -> OnSessionsChanged(SessionsChange sessions_change);

    /// Notifies the `Registry` that the sessions change event was handled
    /// and that the client is ready for more. If you want these events, send
    /// this message on receipt of them. After some amount of events are sent
    /// without receipts, the client will stop receiving events from the
    /// `Registry`.
    ///
    /// Never sending this message has no effect other than unsubscribing from
    /// these events.
    NotifySessionsChangeHandled();

    /// Connects to a `Session` for `session_id` if present.
    ConnectToSessionById(handle<event> session_id, request<Session> session_request);
};