Upstreaming review for Media Router Mojo interface.

chrome/browser/media/router/media_router.mojom

+// Copyright 2015 The Chromium Authors. All rights reserved.

[xhwang, 2015/04/28 06:08:18]

tip: Next time upload a PS with all changes without renaming the file. Then
upload a PS with renaming only. That way it's much easier to see what has been
changed since the last PS.

+// 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.
+
+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 ID of the sink receiving the media.
+  // e.g. "rs71w7mFzYLFlabir_qO4NHl6SUc."
+  string sink_id;
+  // Human readable name of the sink.
+  string sink_name;

[xhwang, 2015/04/28 06:08:18]

Can you replace this two with

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.
+interface ProviderManagerService {

[xhwang, 2015/04/28 06:08:18]

I am still not sure about this naming. Can you just name this
MediaRouterProviderManager, based on your file/interface level comments?

BTW, it's not recommended to name a mojo interface "Service" now based on the
naming discussion thread.

[Kevin M, 2015/04/28 17:20:29]

Based on our discussion about the "Client" naming - how is
MediaRouter+MediaRouterClient?

+  // Signals the client to route the media located

[xhwang, 2015/04/28 06:08:18]

What is a "client"? Maybe just s/client/MediaRouter?

[Kevin M, 2015/04/28 17:20:30]

The call is originating from the MR and sent to the (client|provider).

I'll use "provider" here because changing the name of the interface to
MediaRouterClient means that the "client" target is implied.

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

[xhwang, 2015/04/28 06:08:18]

Is this equivalent to c++ MediaRoutner::RequestRoute()? 

Also, we don't have JoinRoute() on the C++ interface. Is this expected?

[Kevin M, 2015/04/28 17:20:30]

Yes. We changed it to CreateRoute because "request" is ambiguous -- there are
two different modes of route establishment, create-new or join-existing.
That's a work in progress that Derek's working on now. Since that's not yet
fully baked, I'll omit Join from these upstreaming CLs from now on.

+
+  // Signals the client to join an established route given by |presentation_id|
+  // with media located at |media_source|. |origin| and |tab_id| are used for
+  // enforcing same origin/tab scopes.
+  // Returns the route on success. Otherwise an error message is returned.
+  JoinRoute(string media_source,
+            string presentation_id,
+            string origin,
+            int64 tab_id) => (MediaRoute? route, string? error_text);
+
+  // Signals the client 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 client to start querying for sinks
+  // capable of displaying |media_source|.
+  StartObservingMediaSinks(string media_source);
+
+  // Signals the client 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 the client to the MR.
+interface MediaRouter {
+  // Sets a service object for issuing calls back to the MRPM.
+  // Returns a string that uniquely identifies the Media Router browser
+  // process.
+  SetProviderManagerService(ProviderManagerService 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);
+};