chrome/common/extensions/api/webrtc_logging_private.idl

// Copyright 2013 The Chromium Authors
// 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;

    // Use the render process of the webview in the current page. This allows an
    // app to make a request for a webview it contains. If there are more or
    // less than 1 webview, this will fail with a runtime error.
    boolean? targetWebview;
  };

  // This contains information about the result of audio debug recordings.
  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() call.
    boolean didManualStop;
  };

  dictionary StartEventLoggingResult {
    // The log ID. Non-empty if and only if StartEventLogging() was successful.
    DOMString logId;
  };

  callback GenericDoneCallback = void ();
  callback RecordingDoneCallback = void (RecordingInfo info);
  callback UploadDoneCallback = void (UploadResult result);
  callback GetLogsDirectoryCallback = void ([instanceOf = DirectoryEntry] object entry);
  callback StartEventLoggingCallback = void (StartEventLoggingResult 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);

    // Start remote-bound event logging for a specific peer connection,
    // indicated by its session description's ID.
    // If successful, the callback will carry the ID of the log.
    // * |webAppId| must be a number between 1 and 99 (inclusive), which will be
    //   incorporated into the uploaded log, so as to help distinugish logs
    //   captured by different web-apps.
    // * |outputPeriodMs| refers to the time between emissions of logs.
    //   Only non-negative values are allowed. If set to zero, logs will be
    //   produced as soon as an event occurs. If positive, events will be
    //   batched together and emitted approximately every |outputPeriodMs| ms.
    static void startEventLogging(RequestInfo request,
                                  DOMString securityOrigin,
                                  DOMString sessionId,
                                  long maxLogSizeBytes,
                                  long outputPeriodMs,
                                  long webAppId,
                                  StartEventLoggingCallback callback);

    // Returns the directory entry for the "WebRTC Logs" directory. If the
    // directory doesn't exist yet, this will create it. If the directory
    // cannot be created, this call will fail with a runtime error.
    static void getLogsDirectory(GetLogsDirectoryCallback callback);
  };
};