chrome/common/extensions/api/webrtc_logging_private.idl

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.webrtcLoggingPrivate</code> API to control diagnostic
   6 // WebRTC logging.
   7 namespace webrtcLoggingPrivate {
   8   dictionary MetaDataEntry {
   9     // The meta data entry key.
  10     DOMString key;
  11
  12     // The meta data entry value.
  13     DOMString value;
  14   };
  15
  16   dictionary UploadResult {
  17     // The report ID for the uploaded log. Will be empty if not successful.
  18     DOMString reportId;
  19   };
  20
  21   dictionary RequestInfo {
  22     // The tab identifier from the chrome.tabs API, if the request is from a
  23     // tab.
  24     long? tabId;
  25
  26     // The guest process id for the requester, if the request is from a
  27     // webview.
  28     long? guestProcessId;
  29   };
  30
  31   callback GenericDoneCallback = void ();
  32   callback UploadDoneCallback = void (UploadResult result);
  33
  34   interface Functions {
  35     // For all functions, |request| determines which render process to apply
  36     // the operation on. |request| identifies the requesting process.
  37     // |securityOrigin| is the security origin for the tab identified by |tabId|
  38     // and is used for verifying that the tab is the correct one and has not
  39     // been navigated away from.
  40
  41     // Sets additional custom meta data that will be uploaded along with the
  42     // log. |metaData| is a dictionary of the metadata (key, value).
  43     static void setMetaData(RequestInfo request,
  44                             DOMString securityOrigin,
  45                             MetaDataEntry[] metaData,
  46                             GenericDoneCallback callback);
  47
  48     // Starts logging. If logging has already been started for this render
  49     // process, the call will be ignored. |appSessionId| is the unique session
  50     // ID which will be added to the log.
  51     static void start(RequestInfo request,
  52                       DOMString securityOrigin,
  53                       GenericDoneCallback callback);
  54
  55     // Sets whether the log should be uploaded automatically for the case when
  56     // the render process goes away (tab is closed or crashes) and stop has not
  57     // been called before that. If |shouldUpload| is true it will be uploaded,
  58     // otherwise it will be discarded. The default setting is to discard it.
  59     static void setUploadOnRenderClose(RequestInfo request,
  60                                        DOMString securityOrigin,
  61                                        boolean shouldUpload);
  62
  63     // Stops logging. After stop has finished, either upload() or discard()
  64     // should be called, otherwise the log will be kept in memory until the
  65     // render process is closed or logging restarted.
  66     static void stop(RequestInfo request,
  67                      DOMString securityOrigin,
  68                      GenericDoneCallback callback);
  69
  70     // Stores the current log without uploading. The log may stay around for
  71     // as much as 5 days. The application has the option of supplying an id
  72     // for uniquely identifying the log for later upload via a call to
  73     // uploadStored().
  74     static void store(RequestInfo request,
  75                       DOMString securityOrigin,
  76                       DOMString logId,
  77                       GenericDoneCallback callback);
  78
  79     // Uploads a previously kept log that was stored via a call to store().
  80     // The caller needs to know the logId as was originally provided in the
  81     // call to store().
  82     static void uploadStored(RequestInfo request,
  83                              DOMString securityOrigin,
  84                              DOMString logId,
  85                              UploadDoneCallback callback);
  86
  87     // Uploads the log and the RTP dumps, if they exist. Logging and RTP dumping
  88     // must be stopped before this function is called.
  89     static void upload(RequestInfo request,
  90                        DOMString securityOrigin,
  91                        UploadDoneCallback callback);
  92
  93     // Discards the log. Logging must be stopped before this function is called.
  94     static void discard(RequestInfo request,
  95                         DOMString securityOrigin,
  96                         GenericDoneCallback callback);
  97
  98     // Starts RTP dumping. If it has already been started for this render
  99     // process, the call will be ignored.
 100     static void startRtpDump(RequestInfo request,
 101                              DOMString securityOrigin,
 102                              boolean incoming,
 103                              boolean outgoing,
 104                              GenericDoneCallback callback);
 105
 106     // Stops RTP dumping. After stop has finished, the dumps will be
 107     // uploaded with the log if upload is called. Otherwise, the dumps will be
 108     // discarded.
 109     static void stopRtpDump(RequestInfo request,
 110                             DOMString securityOrigin,
 111                             boolean incoming,
 112                             boolean outgoing,
 113                             GenericDoneCallback callback);
 114   };
 115 };