Merge Chromium + Blink git repositories

[chromium-blink-merge.git] / chrome / browser / media / router / media_router.mojom

// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module media_router.interfaces;

// Represents an output sink to which media can be routed.
struct MediaSink {
  enum IconType {
    CAST,
    CAST_AUDIO,
    GENERIC,
    HANGOUT
  };

  // The sink identifier, e.g. "rs71w7mFzYLFlabir_qO4NHl6SUc."
  string sink_id;
  // The human-readable name, e.g. "Janet's Chromecast".
  string name;
  // The type of icon to show in the UI for this media sink.
  IconType icon_type;
  // True if a route is being created to this sink.
  bool is_launching;
};

// Should be kept in sync with media_route.h.
struct MediaRoute {
  // The ID of this media route, e.g. "r_PR1O_blkC9dsKp-tb1ti8qurOo".
  string media_route_id;
  // The ID of the media source being sent through this media route.
  // May be missing if route is not local.
  string? media_source;
  // The ID of sink that is rendering the media content.
  string media_sink_id;
  // Human readable description of this route, e.g.
  // "Tab casting".
  string description;
  // Specifies that the route is requested locally.
  bool is_local;
  // An optional path to an HTML page bundled bundled with the media router
  // component extension. When set, the route can have custom route detail as
  // well as its own route controls in the media router dialog.
  string? custom_controller_path;
  // Set to true if this route should be displayed for |media_sink_id| in UI.
  bool for_display;
};

// Notifications or an actionable events to be shown to the user.
// When is_blocking is true, media router UI shows issue only:
//
//       Title
//       Message
//       default_action_button secondary_action_button
//
// When is_blocking is false, media router UI uses banner:
//
//       Title default_action_link secondary_action_link
//
// above receiver list if route_id is not provided; otherwise it is
// above route detail and controls.
struct Issue {
  enum Severity {
    FATAL,
    WARNING,
    NOTIFICATION
  };

  enum ActionType {
    DISMISS,
    LEARN_MORE
  };

  // If set, the ID of the route to which this issue pertains.
  // If not set (default), then this is a global issue.
  string? route_id;

  Severity severity;

  // When true, the issue must be presented to the user and resolved
  // before other actions are allowed.
  bool is_blocking;

  // Short description about the issue.
  string title;

  // Message about issue detail or how to handle issue.
  // Messages should be suitable for end users to decide which actions to take.
  string? message;

  ActionType default_action;

  array<ActionType>? secondary_actions;

  // A help page to be opened if users select learn_more.
  string? help_url;
};

struct RouteMessage {
  enum Type {
    TEXT,
    BINARY
  };
  // The type of this message.
  Type type;
  // Used when the |type| is TEXT.
  string? message;
  // Used when the |type| is BINARY.
  array<uint8>? data;
};

// Modeled after the MediaRouter interface defined in
// chrome/browser/media/router/media_router.h
interface MediaRouteProvider {
  // Initiates a media route from |media_source| to |sink_id|.
  // The presentation ID of the route created will be |presentation_id|, but it
  // may be overridden by a provider implementation. The presentation ID will
  // be used by the presentation API to refer to the created route.
  // |origin| and |tab_id| may be passed in for enforcing same-origin and/or
  // same-tab scopes.
  // Since int types cannot be made optional, use -1 as |tab_id| in cases where
  // it is not applicable.
  // If the operation was successful, |route| will be defined and
  //     |error_text| will be null.
  // If the operation failed, |route| will be null and |error_text|
  //     will be set.
  CreateRoute(string media_source,
              string sink_id,
              string original_presentation_id,
              string origin,
              int32 tab_id) => (MediaRoute? route, string? error_text);

  // Joins an established route given by |presentation_id|
  // with |media_source|.
  // |origin| and |tab_id| are used for validating same-origin/tab scopes.
  // (See CreateRoute for additional documentation)
  // If the operation was successful, |route| will be defined and
  //     |error_text| will be null.
  // If the operation failed, |route| will be null and |error_text|
  //     will be set.
  JoinRoute(string media_source,
            string presentation_id,
            string origin,
            int32 tab_id) => (MediaRoute? route, string? error_text);

  // Closes the route specified by |route_id|.
  CloseRoute(string route_id);

  // Sends |message| via the media route |media_route_id|.
  // If the operation was successful, |sent| is true; otherwise it is false.
  SendRouteMessage(string media_route_id, string message) => (bool sent);

  // Sends |data| via the media route |media_route_id|.
  // If the operation was successful, |sent| is true; otherwise it is false.
  SendRouteBinaryMessage(string media_route_id, array<uint8> data)
      => (bool sent);

  // Starts querying for sinks capable of displaying |media_source|.
  StartObservingMediaSinks(string media_source);

  // Stops querying sinks for |media_source|.
  StopObservingMediaSinks(string media_source);

  // Starts reporting the state of active media routes via
  // OnRoutesUpdated(). Querying will continue until
  // StopObservingMediaRoutes() is called.
  StartObservingMediaRoutes();

  // Stops querying the state of all media routes.
  StopObservingMediaRoutes();

  // Called when the MediaRouter is ready to get the next batch of messages
  // associated with |route_id|.
  // |messages| returned will contain the batch of messages.
  // |messages| will be empty if |StopListeningForRouteMessages| was invoked.
  // |error| indicates if a permanent error occurred. If true, then subsequent
  // calls will also return with |error| being true.
  ListenForRouteMessages(string route_id) =>
      (array<RouteMessage> messages, bool error);

  // Called when there are no more listeners for messages for |route_id|.
  // Calling this will resolve the pending |ListenForRouteMessages| callback
  // with an empty list.
  StopListeningForRouteMessages(string route_id);

  // Indicates that the presentation session that was connected to route
  // |route_id| is no longer connected to it.
  OnPresentationSessionDetached(string route_id);
};

// Interface for a service which observes state changes across media
// sources, sinks, and issues.
interface MediaRouter {
  // Registers a MediaRouteProvider with the MediaRouter.
  // Returns a string that uniquely identifies the Media Router browser
  // process.
  RegisterMediaRouteProvider(MediaRouteProvider media_router_provider) =>
      (string instance_id);

  // Called when the Media Route Manager receives a new list of sinks.
  OnSinksReceived(string media_source, array<MediaSink> sinks);

  // Called when issues are reported for media routes.
  OnIssue(Issue issue);

  // Called when list of routes has been updated.
  OnRoutesUpdated(array<MediaRoute> routes);
};