Media Remoting: Data/Control plumbing between renderer and Media Router.

media/mojo/interfaces/remoting.mojom

+// Copyright 2016 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.mojom;
+
+interface RemoterFactory {
+  // Create a new Remoter associated with the given RemotingSource and bind it
+  // to the given interface request. The RemotingSource will be notified when
+  // the Remoter becomes available for use (or becomes unavailable).
+  Create(RemotingSource source, Remoter& remoter);
+};
+
+// Interface used by the source to control when media bitstream data is read
+// from the data pipes and then sent to the remote endpoint.
+interface RemotingDataStreamSender {
+  // Consumes |size| bytes of data from the data pipe, which is a chunk of the

[Ken Rockot(use gerrit already), 2016/09/12 15:26:05]

doc nit: From which data pipe?

[miu, 2016/09/14 23:55:30]

The one and only. ;-)

So, my comments for the whole RemotingDataStreamSender interface made it look
like one of these controlled both data pipes. Instead, there is one RDSSender
per data pipe. I fixed the comment to clarify this.

+  // next frame's data payload starting at the given byte |offset|.
+  // |total_payload_size| indicates the size of the entire data payload for the
+  // frame. Before this is called, |size| bytes of data must have been written
+  // into the data pipe.
+  //
+  // Normally, a frame's entire data payload can be pushed through the data pipe
+  // in one chunk. However, there can be situations where the size of the
+  // payload exceeds the capacity of the data pipe; and so this API supports
+  // feeding the frame data through the pipe in multiple chunks.
+  ConsumeDataChunk(uint32 offset, uint32 size, uint32 total_payload_size);
+
+  // Enqueues another frame for transmission to the remote endpoint. Before this
+  // is called, ConsumeDataChunk() must have been called one or more times to
+  // provide all of the frame's data.
+  SendFrame();
+
+  // Cancel the transmission of all in-flight data to the remote, up to and
+  // including the last SendFrame() call; and also discard any data chunks

[Ken Rockot(use gerrit already), 2016/09/12 15:26:05]

doc nit: Is this an accurate guarantee? Can't a call to CancelInFlightData()
race with transmission of in-flight data?

[miu, 2016/09/14 23:55:30]

Yes. Cancel in this context means "I decided not to send the data
after-the-fact, so just don't send any more data than you already have." I added
a sentence to explain that there is no guarantee as to how much of the in-flight
data will reach the remote.

+  // that were consumed from the data pipe for the next frame. This is used to
+  // optimize seeking, when it is known that any in-flight data is no longer
+  // needed by the remote.
+  CancelInFlightData();
+};
+
+enum RemotingStopReason {
+  ROUTE_TERMINATED,  // User-initiated disconnect, etc.
+  LOCAL_PLAYBACK,  // Media switched back to local playback.
+  SOURCE_GONE,  // RemotingSource has been destroyed.
+  MESSAGE_SEND_FAILED,  // Failed to send a message to the sink.
+  DATA_SEND_FAILED,  // Failed to consume from a data pipe or send to the sink.
+  UNEXPECTED_FAILURE,  // Unexpected failure or inconsistent state encountered.
+};
+
+// Interface used by the source to start/stop remoting and send data to the
+// sink.
+interface Remoter {
+  // Start a remoting session (once the sink has been reported to be available;
+  // see RemotingSource). Either RemotingSource.OnStarted() or OnStartFailed()
+  // will be called to indicate success or failure. Once OnStarted() has been
+  // invoked, the source may then make calls to SendMessageToSink() and expect
+  // messages from the remote via RemotingSource.OnMessageFromSink().
+  Start();
+
+  // Start remoting the media data streams. This is called after Start() to
+  // provide data pipes from which the audio/video bitstream data is consumed
+  // and then transported to the remote device. RemotingDataStreamSenders are
+  // used by the source to control when data should be consumed from the data
+  // pipes and sent. One or both pipes (and their corresponding
+  // RemotingDataStreamSender interface requests) must be provided.
+  StartDataStreams(handle<data_pipe_consumer>? audio_pipe,
+                   handle<data_pipe_consumer>? video_pipe,
+                   RemotingDataStreamSender&? audio_sender,
+                   RemotingDataStreamSender&? video_sender);
+
+  // Stop remoting media. Messages in both directions will be dropped after this
+  // point as well as any pending or in-transit media bitstream data.
+  Stop(RemotingStopReason reason);
+
+  // Send |message| to the sink. |message| is a serialized protobuf from
+  // src/media/remoting/proto.
+  SendMessageToSink(array<uint8> message);
+};
+
+enum RemotingStartFailReason {
+  CANNOT_START_MULTIPLE,  // Remoting was already active.
+  ROUTE_TERMINATED,  // User-initated disconnect while starting remoting.
+};
+
+// Interface used for sending notifications back to the local source's control
+// logic, and to pass messages from the sink back to the local media pipeline.
+interface RemotingSource {
+  // Notify the source that the sink is now available to start remoting. It is
+  // up to the source's control logic to decide whether/when to start remoting.
+  //
+  // TODO(miu): In a later change, also pass information about the sink's
+  // capabilities (e.g., codec support, DRM keysystem support, etc.).
+  OnSinkAvailable();
+
+  // Notify the source that the sink is no longer available for remoting. This
+  // may happen, for example, because the sink has been shut down, or because
+  // another source has started remoting.
+  OnSinkGone();
+
+  // One of these is called after the source attempts to start remoting. If
+  // OnStarted() is called, messages may begin flowing; and this will continue
+  // until OnStopped() is called. On the other hand, if OnStartFailed() is
+  // called, then no messages are being passed between source and sink and
+  // remoting is not taking place.
+  OnStarted();
+  OnStartFailed(RemotingStartFailReason reason);
+
+  // Pass a |message| from the sink back to the source. The |message| consists
+  // of a serialized protobuf from src/media/remoting/proto. This will only be
+  // called after OnStarted() and before OnStopped().
+  OnMessageFromSink(array<uint8> message);
+
+  // Notify the source that remoting has terminated. This may or may not be in
+  // response to a Remoter.Stop() call, as other events (possibly external) may
+  // have caused remoting to end.
+  OnStopped(RemotingStopReason reason);
+};