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

// Use the <code>chrome.webrtcLoggingPrivate</code> API to control diagnostic
// WebRTC logging.
[nodoc] namespace webrtcLoggingPrivate {
  dictionary MetaDataEntry {
    // The meta data entry key.
    DOMString key;

    // The meta data entry value.
    DOMString value;
  };

  dictionary UploadResult {
    // The report ID for the uploaded log. Will be empty if not successful.
    DOMString reportId;
  };

  callback GenericDoneCallback = void ();
  callback UploadDoneCallback = void (UploadResult result);

  interface Functions {
    // For all functions, |tabId| determines which render process to apply
    // the operation on. |tabId| is the identifier from the chrome.tabs API.
    // |securityOrigin| is the security origin for the tab identified by |tabId|
    // and is used for verifying that the tab is the correct one and has not
    // been navigated away from.

    // Sets additional custom meta data that will be uploaded along with the
    // log. |metaData| is a dictionary of the metadata (key, value).
    static void setMetaData(long tabId,
                            DOMString securityOrigin,
                            MetaDataEntry[] metaData,
                            GenericDoneCallback callback);

    // Starts logging. If logging has already been started for this render
    // process, the call will be ignored. |appSessionId| is the unique session
    // ID which will be added to the log.
    static void start(long tabId,
                      DOMString securityOrigin,
                      GenericDoneCallback callback);

    // Sets whether the log should be uploaded automatically for the case when
    // the render process goes away (tab is closed or crashes) and stop has not
    // been called before that. If |shouldUpload| is true it will be uploaded,
    // otherwise it will be discarded. The default setting is to discard it.
    static void setUploadOnRenderClose(long tabId,
                                       DOMString securityOrigin,
                                       boolean shouldUpload);

    // Stops logging. After stop has finished, either upload() or discard()
    // should be called, otherwise the log will be kept in memory until the
    // render process is closed or logging restarted.
    static void stop(long tabId,
                     DOMString securityOrigin,
                     GenericDoneCallback callback);

    // Uploads the log and the RTP dumps, if they exist. Logging and RTP dumping
    // must be stopped before this function is called.
    static void upload(long tabId,
                       DOMString securityOrigin,
                       UploadDoneCallback callback);

    // Discards the log. Logging must be stopped before this function is called.
    static void discard(long tabId,
                        DOMString securityOrigin,
                        GenericDoneCallback callback);

    // Starts RTP dumping. If it has already been started for this render
    // process, the call will be ignored.
    static void startRtpDump(long tabId,
                             DOMString securityOrigin,
                             boolean incoming,
                             boolean outgoing,
                             GenericDoneCallback callback);

    // Stops RTP dumping. After stop has finished, the dumps will be
    // uploaded with the log if upload is called. Otherwise, the dumps will be
    // discarded.
    static void stopRtpDump(long tabId,
                            DOMString securityOrigin,
                            boolean incoming,
                            boolean outgoing,
                            GenericDoneCallback callback);
  };
};