Upstreaming review for Media Router Mojo interface.

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.
+
+// Defines communication between the Media Router and the
+// Media Router Provider Manager.

[xhwang, 2015/04/28 17:44:18]

"Media Router Provider Manager" is an implementation detail. In this mojom file,
we are only defining the MR and MRC interfaces.

[Kevin M, 2015/04/28 21:00:26]

Removed introductory comment since it seems redundant.

+
+module media_router.interfaces;
+
+// Represents an output sink to which media can be routed.
+struct MediaSink {
+  // The sink identifier, e.g. "rs71w7mFzYLFlabir_qO4NHl6SUc."
+  string sink_id;
+  // The human-readable name, e.g. "Janet's Chromecast".
+  string name;
+};
+
+// 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 sink that is rendering the media content.
+  MediaSink media_sink;
+  // Human readable description of this route, e.g.
+  // "Tab casting".
+  string description;
+  // An icon that is associated with this media source.
+  string? icon_url;
+  // Specifies that the route is requested locally.
+  bool is_local;
+};
+
+// 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 {
+    OK,
+    CANCEL,
+    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;
+};
+
+// Interface for sending messages from the Media Router to the
+// Media Router Provider Manager.

[xhwang, 2015/04/28 17:44:19]

ditto

+interface MediaRouterClient {

[xhwang, 2015/04/28 17:44:19]

I still feel we have the names inverted. From an design's perspective, it'll be
very confusing that a mojo MediaRouter interface is fundamentally different than
a C++ MediaRouter interface.

I understand that the real MediaRouter implementation (say MediaRouterImpl) will
receive messages back from the MediaRouterProviderManager. But this is
implementation detail. You can think it this way:

- The MediaRouterImpl provides services to callers in the browser process to
provide services like CreateRoute().
- The MediaRouterImpl needs a remote MediaRouter (via mojo, e.g. MediaRouterPtr)
to help to do some work (e.g. CreateRoute()).
- When working with the remote MediaRouter, the MediaRouterImpl serves as a
MediaRouterClient.

With this, MediaRouter is a consistent interface, you can have definitions like:
- MediaRouter: An interface to help create, manage (via PostMessage) and close
MediaRoutes.
- MediaRouterClient: A client interface of MediaRouter to receive MediaRoute
related updates.

WDYT?

+  // Signals the provider to route the media located

[xhwang, 2015/04/28 17:44:18]

Now looking at the interface, we only have MediaRouter and MediaRouterClient. We
don't need to introduce/mention a "provider" here, which is an implementation
detail.

Also now we do have a "client", and we can use "client" in the comments.

+  // at |media_source| to |sink_id|.
+  // 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) =>
+      (MediaRoute? route, string? error_text);
+
+  // Signals the provider to close the route specified by |route_id|.
+  CloseRoute(string route_id);
+
+  // Sends |message| with optional |extra_info_json| via the media route
+  // |media_route_id|.
+  PostMessage(string media_route_id, string message);
+
+  // Signals the provider to start querying for sinks
+  // capable of displaying |media_source|.
+  StartObservingMediaSinks(string media_source);
+
+  // Signals the provider to stop querying for sinks
+  // capable of displaying |media_source|.
+  StopObservingMediaSinks(string media_source);
+
+  // Signals the to start a query on all routes. Updates are received from
+  // |OnRoutesUpdated()|.
+  StartObservingMediaRoutes();
+
+  // Signals the to stop query on all routes.
+  StopObservingMediaRoutes();
+
+  // "Clears" an issue after it has been processed.
+  ClearIssue(string issue_id);
+};
+
+// Interface for sending messages from providers to the MR.
+interface MediaRouter {
+  // Sets a client object so the MR can issue calls back to the
+  // Provider Manager.

[xhwang, 2015/04/28 17:44:18]

ditto

+  // Returns a string that uniquely identifies the Media Router browser
+  // process.
+  SetClient(MediaRouterClient observer) => (string instance_id);
+
+  // Called when the Media Route Manager receives a new list of sinks.
+  OnSinksReceived(string media_source, array<MediaSink> sinks);
+
+  // Called when the Media Route Manager receives a route message.
+  OnMessage(string media_source, string message);
+
+  // Called when providers send an issue.
+  OnIssue(Issue issue);
+
+  // Called when list of routes has been updated.
+  OnRoutesUpdated(array<MediaRoute> routes);
+};
+