chrome/browser/media/router/mojo/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.mojom;

import "mojo/common/common_custom_types.mojom";

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

  // The sink identifier, e.g. "rs71w7mFzYLFlabir_qO4NHl6SUc."
  string sink_id;
  // The human-readable name, e.g. "Janet's Chromecast".
  string name;
  // Optional description of the sink.
  string? description;
  // Optional domain of the sink if this sink is associated with an identity.
  string? domain;
  // The type of icon to show in the UI for this media sink.
  IconType icon_type;
};

// 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;
  // Set to true if this route was created by an incognito profile.
  bool is_incognito;
  // Set to true if this route corresponds to an offscreen presentation.
  bool is_offscreen_presentation;
};

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

  // The ID of the help page to be opened if users select learn_more.
  int32 help_page_id;
};

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

struct SinkSearchCriteria {
  // Input to the search method which each Media Route Provider may interpret
  // differently.
  string input;
  // The user's current hosted domain.
  string domain;
};

// Keep in sync with:
// - RouteRequestResult::ResultCode in route_request_result.h
// - MediaRouteProviderResult enum in tools/metrics/histograms.xml.
// - mr.RouteRequestResultCode in route_request_error.js
enum RouteRequestResultCode {
  UNKNOWN_ERROR,
  OK,
  TIMED_OUT,
  ROUTE_NOT_FOUND,
  SINK_NOT_FOUND,
  INVALID_ORIGIN,
  INCOGNITO_MISMATCH,
  NO_SUPPORTED_PROVIDER
// New values must be added here.
};

// Modeled after the MediaRouter interface defined in
// chrome/browser/media/router/media_router.h
interface MediaRouteProvider {
  // Creates a media route from |media_source| to the sink given by |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. Use -1 as |tab_id| in cases where the request is not
  // made on behalf of a tab.
  //
  // If |timeout| is positive, it will be used in place of the default timeout
  // defined by Media Route Provider Manager.
  //
  // If |incognito| is true, the request was made by an incognito profile.
  //
  // 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.
  // |result| will be set to OK if successful, or an error code if an error
  // occurred.
  CreateRoute(string media_source,
              string sink_id,
              string original_presentation_id,
              string origin,
              int32 tab_id,
              mojo.common.mojom.TimeDelta timeout,
              bool incognito) =>
                  (MediaRoute? route,
                   string? error_text,
                   RouteRequestResultCode result_code);

  // Requests a connection to an established route for |media_source| given
  // by |presentation_id|.
  //
  // |origin| and |tab_id| are used for validating same-origin/tab scopes;
  // see CreateRoute for additional documentation.
  //
  // If |timeout| is positive, it will be used in place of the default timeout
  // defined by Media Route Provider Manager.
  //
  // If the route request was created by an incognito profile,
  // |incognito| must be true.
  //
  // 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.
  // |result| will be set to OK if successful, or an error code if an error
  // occurred.
  JoinRoute(string media_source,
            string presentation_id,
            string origin,
            int32 tab_id,
            mojo.common.mojom.TimeDelta timeout,
            bool incognito) =>
                (MediaRoute? route,
                 string? error_text,
                 RouteRequestResultCode result_code);

  // Creates a new route for |media_source| that connects to the established
  // route given by |route_id|.
  //
  // The presentation ID of the new route 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| are used for validating same-origin/tab scopes; see
  // CreateRoute for additional documentation.
  //
  // If |timeout| is positive, it will be used in place of the default timeout
  // defined by Media Route Provider Manager; see CreateRoute for additional
  // documentation.
  //
  // If the route request was created by an incognito profile,
  // |incognito| must be true.
  //
  // 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.
  //
  // |result| will be set to OK if successful, or an error code if an error
  // occurred.
  ConnectRouteByRouteId(string media_source,
                        string route_id,
                        string presentation_id,
                        string origin,
                        int32 tab_id,
                        mojo.common.mojom.TimeDelta timeout,
                        bool incognito) =>
                            (MediaRoute? route,
                             string? error_text,
                             RouteRequestResultCode result_code);

  // Terminates the route specified by |route_id|.  If the route was terminated
  // successfully, |result_code| is set to OK and |error_text| is null.
  // Otherwise, |result_code| is an error code and |error_text| describes the
  // error.
  TerminateRoute(string route_id) =>
      (string? error_text, RouteRequestResultCode result_code);

  // 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() in the context of the |media_source|.  The
  // |media_source| represents the application interested in the media
  // routes (usually the web page from which the content originates).
  // If no |media_source| is given, this should be considered an
  // observer that is not associated with a media source, and thus
  // cannot connect to a remote route without showing a source.  The
  // |media_source| should be considered when returning joinable routes in the
  // OnRoutesUpdated() call. If an empty |media_source| is given, there is no
  // context in which a joinable route makes sense and therefore, there should
  // not be any joinable routes returned in OnRoutesUpdated().
  // Querying will continue until StopObservingMediaRoutes() is called with
  // the same |media_source| (even if it's an empty string).
  StartObservingMediaRoutes(string media_source);

  // Stops querying the state of all media routes in the context of
  // the |media_source|.  StartObservingMediaRoutes() has
  // to be called with the same |media_source| for this to have any effect even
  // if it's empty.  Thus, StartObservingMediaRoutes(media_source) must be
  // matched with StopObservingMediaRoutes(media_source).
  // Calling StopObservingMediaRoutes() without a media_source will stop
  // any media routes queries associated with emtpy strings (queries
  // that being with StartObservingMediaRoutes()).
  StopObservingMediaRoutes(string media_source);

  // Starts listening for messages from the media sink for the route given by
  // |route_id|.
  // |MediaRouter::OnRouteMessagesReceived| will be invoked when a batch of
  // messages arrives, or when there is an error.
  // |StopListeningForRouteMessages| will stop the Media Router from receiving
  // further messages for |route_id|.
  StartListeningForRouteMessages(string route_id);

  // Called when there are no more listeners for messages for |route_id|.
  StopListeningForRouteMessages(string route_id);

  // Indicates that a PresentationConnection that was connected to route
  // |route_id| has been closed (via .close(), garbage collection or
  // navigation).
  DetachRoute(string route_id);

  // Enables mDNS discovery. No-op if mDNS discovery is already enabled.
  // Calling this will trigger a firewall prompt on Windows if there is not
  // already a firewall rule for mDNS.
  EnableMdnsDiscovery();

  // Updates media sinks capable of displaying |media_source|.
  UpdateMediaSinks(string media_source);

  // Indicates that the Media Router is interested in finding a sink that
  // matches |search_criteria| and is compatible with the source urn
  // |media_source|. |search_criteria| should contain an exact copy of the user
  // input. The user's current domain is also used to search.  The domain is the
  // hosted domain of the user's signed-in identity, or empty if the user has no
  // domain or is not signed in.
  SearchSinks(string sink_id,
              string media_source,
              SinkSearchCriteria search_criteria) =>
                  (string sink_id);
};

// Interface for a service which observes state changes across media
// sources, sinks, and issues.
interface MediaRouter {

  // Represents overall media sink availability states.
  // UNAVAILABLE - No sinks are available.
  // PER_SOURCE - Sinks are available, but are only compatible with specific
  //              media sources.
  // AVAILABLE - A sink is available regardless of source.
  enum SinkAvailability {
    UNAVAILABLE,
    PER_SOURCE,
    AVAILABLE
  };

  // Keep in sync with content/public/browser/presentation_session.h.
  enum PresentationConnectionState {
    CONNECTING,
    CONNECTED,
    CLOSED,
    TERMINATED
  };

  // Keep in sync with content/public/browser/presentation_session.h.
  enum PresentationConnectionCloseReason {
    CONNECTION_ERROR,
    CLOSED,
    WENT_AWAY
  };

  // 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|
  // compatible with |media_source|. The result is only valid for |origins|. If
  // |origins| is empty, the result is valid for any origin.
  OnSinksReceived(string media_source, array<MediaSink> sinks,
      array<string> origins);

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

  // Called when list of routes has been updated in the context of the
  // calling |media_source|.  The array |joinable_route_ids| should
  // contain route IDs of joinable routes found in the |routes| array.
  OnRoutesUpdated(array<MediaRoute> routes, string media_source,
      array<string> joinable_route_ids);

  // Called when the overall availability of media sinks has been updated.
  OnSinkAvailabilityUpdated(SinkAvailability availability);

  // Called when the state of presentation connected to route |route_id| has
  // changed to |state|.
  OnPresentationConnectionStateChanged(
      string route_id, PresentationConnectionState state);

  // Called when the presentation connected to route |route_id| has closed.
  OnPresentationConnectionClosed(
      string route_id, PresentationConnectionCloseReason reason,
      string message);

  // Called when the a batch of messages arrives from the media sink for the
  // route given by |route_id|.
  // |StartListeningForRouteMessages| must be called first in order to receive
  // messages.
  // |route_id|: ID of route of the messages.
  // |messages|: A non-empty list of messages received.
  OnRouteMessagesReceived(string route_id,
                          array<RouteMessage> messages);
};