chrome/common/extensions/api/tab_capture.idl

   1 // Copyright (c) 2012 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.tabCapture</code> API to interact with tab media
   6 // streams.
   7 namespace tabCapture {
   8
   9   enum TabCaptureState {
  10     pending,
  11     active,
  12     stopped,
  13     error
  14   };
  15
  16   dictionary CaptureInfo {
  17     // The id of the tab whose status changed.
  18     long tabId;
  19
  20     // The new capture status of the tab.
  21     TabCaptureState status;
  22
  23     // Whether an element in the tab being captured is in fullscreen mode.
  24     boolean fullscreen;
  25   };
  26
  27   // MediaTrackConstraints for the media streams that will be passed to WebRTC.
  28   // See section on MediaTrackConstraints:
  29   // http://dev.w3.org/2011/webrtc/editor/getusermedia.html
  30   dictionary MediaStreamConstraint {
  31     object mandatory;
  32     object? _optional;
  33   };
  34
  35   // Whether we are requesting tab video and/or audio and the
  36   // MediaTrackConstraints that should be set for these streams.
  37   dictionary CaptureOptions {
  38     boolean? audio;
  39     boolean? video;
  40     MediaStreamConstraint? audioConstraints;
  41     MediaStreamConstraint? videoConstraints;
  42   };
  43
  44   callback GetTabMediaCallback =
  45       void ([instanceOf=LocalMediaStream] object stream);
  46
  47   callback GetCapturedTabsCallback = void (CaptureInfo[] result);
  48
  49   interface Functions {
  50     // Captures the visible area of the currently active tab.  Capture can
  51     // only be started on the currently active tab after the extension has been
  52     // <em>invoked</em>.  Capture is maintained across page navigations within
  53     // the tab, and stops when the tab is closed, or the media stream is closed
  54     // by the extension.
  55     //
  56     // |options| : Configures the returned media stream.
  57     // |callback| : Callback with either the tab capture stream or
  58     //   <code>null</code>.
  59     static void capture(CaptureOptions options,
  60                         GetTabMediaCallback callback);
  61
  62     // Returns a list of tabs that have requested capture or are being
  63     // captured, i.e. status != stopped and status != error.
  64     // This allows extensions to inform the user that there is an existing
  65     // tab capture that would prevent a new tab capture from succeeding (or
  66     // to prevent redundant requests for the same tab).
  67     // |callback| : Callback invoked with CaptureInfo[] for captured tabs.
  68     static void getCapturedTabs(GetCapturedTabsCallback callback);
  69   };
  70
  71   interface Events {
  72     // Event fired when the capture status of a tab changes.
  73     // This allows extension authors to keep track of the capture status of
  74     // tabs to keep UI elements like page actions in sync.
  75     // |info| : CaptureInfo with new capture status for the tab.
  76     static void onStatusChanged(CaptureInfo info);
  77   };
  78
  79 };