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

  dictionary RequestInfo {
    // The tab identifier from the chrome.tabs API, if the request is from a
    // tab.
    long? tabId;

    // The guest process id for the requester, if the request is from a
    // webview.
    long? guestProcessId;
  };

  // This contains information about the result of audio debug recordings or
  // WebRTC event logs.
  dictionary RecordingInfo {
    // Absolute path prefix for the files with the audio debug recordings.
    DOMString prefixPath;

    // Indicates if recording was stopped (either by a timed callback after the
    // time limit has elapsed, or by a manual call).
    boolean didStop;

    // Indicates if recording was stopped manually through a
    // stopAudioDebugRecordings() or stopWebRtcEventLogging() call.
    boolean didManualStop;
  };

  callback GenericDoneCallback = void ();
  callback RecordingDoneCallback = void (RecordingInfo info);
  callback UploadDoneCallback = void (UploadResult result);

  interface Functions {
    // For all functions, |request| determines which render process to apply
    // the operation on. |request| identifies the requesting process.
    // |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(RequestInfo request,
                            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(RequestInfo request,
                      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(RequestInfo request,
                                       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(RequestInfo request,
                     DOMString securityOrigin,
                     GenericDoneCallback callback);

    // Stores the current log without uploading. The log may stay around for
    // as much as 5 days. The application has the option of supplying an id
    // for uniquely identifying the log for later upload via a call to
    // uploadStored().
    static void store(RequestInfo request,
                      DOMString securityOrigin,
                      DOMString logId,
                      GenericDoneCallback callback);

    // Uploads a previously kept log that was stored via a call to store().
    // The caller needs to know the logId as was originally provided in the
    // call to store().
    static void uploadStored(RequestInfo request,
                             DOMString securityOrigin,
                             DOMString logId,
                             UploadDoneCallback 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(RequestInfo request,
                       DOMString securityOrigin,
                       UploadDoneCallback callback);

    // Discards the log. Logging must be stopped before this function is called.
    static void discard(RequestInfo request,
                        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(RequestInfo request,
                             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(RequestInfo request,
                            DOMString securityOrigin,
                            boolean incoming,
                            boolean outgoing,
                            GenericDoneCallback callback);

    // Starts audio debug recordings.
    // |seconds| indicates how many seconds of audio to record. |callback|
    // is invoked once recording stops.
    // If |seconds| is zero, recording will continue until
    // stopAudioDebugRecordings() is explicitly called. In this case,
    // |callback| is invoked once recording starts and will report
    // that recording has not stopped.
    // If |seconds| is negative, startAudioDebugRecordings() fails.
    static void startAudioDebugRecordings(RequestInfo request,
                                          DOMString securityOrigin,
                                          long seconds,
                                          RecordingDoneCallback callback);

    // Stops audio debug recordings.  |callback| is invoked once recording
    // stops. If there is no recording in progress, stopAudioDebugRecordings()
    // fails.
    static void stopAudioDebugRecordings(RequestInfo request,
                                         DOMString securityOrigin,
                                         RecordingDoneCallback callback);

    // Starts WebRTC event logging.
    // startWebRtcEventLogging() logs the most recent events that happened
    // before the call, and then keep logging for |seconds| seconds into the
    // future. |callback| is invoked once the logging stops.
    // If |seconds| is zero, the logging will continue until
    // stopWebRtcEventLogging() is explicitly called. In this case,
    // |callback| is invoked once recording starts and will report
    // that recording has not stopped.
    // If |seconds| is negative, startWebRtcEventLogging() fails.
    static void startWebRtcEventLogging(RequestInfo request,
                                        DOMString securityOrigin,
                                        long seconds,
                                        RecordingDoneCallback callback);

    // Stops RTC event logging. |callback| is invoked once the logging stops.
    // If there is no recording in progress, stopWebRtcEventLogging() fails.
    static void stopWebRtcEventLogging(RequestInfo request,
                                       DOMString securityOrigin,
                                       RecordingDoneCallback callback);
  };
};
