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

// The <code>chrome.cast.streaming.rtpStream</code> API allows configuration
// of encoding parameters and RTP parameters used in a Cast streaming
// session.
//
// Valid stream IDs are positive and non-zero.
namespace cast.streaming.rtpStream {
  // Params for audio and video codec.
  dictionary CodecSpecificParams {
    DOMString key;
    DOMString value;
  };

  // RTP payload param.
  dictionary RtpPayloadParams {
    long payloadType;

    // Maximum latency in milliseconds. This parameter controls the logic
    // of flow control. Implementation can adjust latency adaptively and
    // tries to keep it under this threshold. A larger value allows smoother
    // playback at the cost of higher latency.
    long maxLatency;

    DOMString codecName;

    // Synchronization source identifier.
    long ssrc;

    long feedbackSsrc;

    long? clockRate;

    // Minimum bitrate in kilobits per second.
    long? minBitrate;

    // Maximum bitrate in kilobits per second.
    long? maxBitrate;

    // The number of channels.
    long? channels;

    // Video width in pixels.
    long? width;

    // Video height in pixels.
    long? height;

    // 32 bytes hex-encoded AES key.
    DOMString? aesKey;

    // 32 bytes hex-encoded AES IV (Initialization vector) mask.
    DOMString? aesIvMask;

    // A list of codec specific params.
    CodecSpecificParams[] codecSpecificParams;
  };

  // Cast RTP parameters.
  dictionary RtpParams {
    // RTP payload params.
    RtpPayloadParams payload;

    DOMString[] rtcpFeatures;
  };

  // Callback from the <code>create</code> method.
  // |id| : The ID for the RTP stream.
  callback CreateCallback = void (long streamId);

  // Callback from the <code>getRawEvents</code> method.
  // |rawEvents|: compressed serialized raw bytes containing raw events
  //              recorded for a stream.
  // The compression is in gzip format.
  // The serialization format can be found at 
  // media/cast/logging/log_serializer.cc.
  callback GetRawEventsCallback = void (ArrayBuffer rawEvents);
  
  // Callback from the <code>getStats</code> method.
  // |rawEvents|: dictionary object containing stats recorded for a stream.
  // The format can be found at 
  // media/cast/logging/stats_converter.cc.
  callback GetStatsCallback = void (object stats);

  interface Functions {
    // Destroys a Cast RTP stream.
    // |streamId| : The RTP stream ID.
    [nocompile] static void destroy(long streamId);

    // Returns an array of supported parameters with default values.
    // This includes a list of supported codecs on this platform and
    // corresponding encoding and RTP parameters.
    // |streamId| : The RTP stream ID.
    [nocompile] static RtpParams[] getSupportedParams(long streamId);

    // Activates the RTP stream by providing the parameters.
    // |streamId| : The RTP stream ID.
    // |params| : Parameters set for this stream.
    [nocompile] static void start(long streamId, RtpParams params);

    // Stops activity on the specified stream.
    // |streamId| : The RTP stream ID.
    [nocompile] static void stop(long streamId);

    // Enables / disables logging for a stream.
    // |enable|: If true, enables logging. Otherwise disables logging.
    [nocompile] static void toggleLogging(long streamId, boolean enable);
    
    // Get raw events for a stream in the current session.
    // |streamId|: Stream to get events for.
    // |callback|: Called with the raw events.
    [nocompile] static void getRawEvents(
        long streamId, GetRawEventsCallback callback);
    
    // Get stats for a stream in the current session.
    // |streamId|: Stream to get stats for.
    // |callback|: Called with the stats.
    [nocompile] static void getStats(
        long streamId, GetStatsCallback callback);
  };

  interface Events {
    // Event fired when a Cast RTP stream has started.
    // |streamId| : The ID of the RTP stream.
    static void onStarted(long streamId);

    // Event fired when a Cast RTP stream has stopped.
    // |streamId| : The ID of the RTP stream.
    static void onStopped(long streamId);

    // Event fired when a Cast RTP stream has error.
    // |streamId| : The ID of the RTP stream.
    // |errorString| : The error info.
    static void onError(long streamId, DOMString errorString);
  };
};