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

[DartPackage="mojo_services"]
module mojo.media;

import "mojo/services/media/common/interfaces/media_common.mojom";
import "mojo/services/media/common/interfaces/media_pipe.mojom";
import "mojo/services/media/common/interfaces/media_types.mojom";

// Models a stream producer. A MediaProducer allows a client to connect the
// producer to a MediaConsumer so packets flow from the producer to the
// consumer. Clients who want to receive packets directly from the producer
// should use MediaPullModeProducer instead.
//
// The client calls Connect to connect producer and consumer. The producer then
// calls PushPacket on the consumer to deliver packets.
interface MediaProducer {
  // Connects this MediaProducer to a MediaConsumer.
  Connect(MediaConsumer consumer) => ();

  // Disconnects this MediaProducer from a previously-connected MediaConsumer.
  Disconnect();
};

// Models a stream producer. A MediaPullModeProducer allows a client to receive
// packets directly from the producer. Clients who want to connect the producer
// to a MediaConsumer should use MediaProducer instead.
//
// The client calls PullPacket to get a packet. Once the client is done with
// the packet, it calls ReleasePacket to let the producer know that the packet
// buffer region can be reused. Alternatively, the client can piggyback a
// release on a PullPacket call using the to_release parameter.
interface MediaPullModeProducer {
  // Gets the shared buffer in which packet payload will be located.
  GetBuffer() => (handle<shared_buffer> buffer);

  // Pulls a packet from the producer. When the client is done with the
  // packet buffer region, it should call ReleasePacket or PullPacket passing
  // the locator. Note that the optional locator passed in PullPacket is
  // a locator to be released and probably won't be the same locator passed
  // back in the callback.
  PullPacket(MediaPacket? to_release) => (MediaPacket packet);

  // Signals the producer that the client is done with the buffer region.
  ReleasePacket(MediaPacket to_release);
};

// Models a stream consumer. A MediaConsumer allows a client to send packets
// directly to the consumer or to connect the consumer to a MediaProducer so
// packets flow from the producer to the consumer.
//
// In the former scenario, the client calls PushPacket to deliver a packet. The
// callback notifies the client that the consumer is done with the packet
// buffer region.
//
// In the latter scenario, the client calls Connect on the producer to connect
// producer and consumer. The producer then calls PushPacket on the consumer to
// deliver packets.
interface MediaConsumer {
  // Sets the shared buffer in which packet payload will be located.
  SetBuffer(handle<shared_buffer> buffer, uint64 size) => ();

  // Pushes a packet to the consumer. The callback signals that the consumer
  // is done with the packet buffer region.
  PushPacket(MediaPacket packet) => ();
};