src/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.
  51     // This method can only be used on the currently active page after the
  52     // extension has been <em>invoked</em>, similar to the way that
  53     // <a href="activeTab.html">activeTab</a> works.
  54     // |options| : Configures the returned media stream.
  55     // |callback| : Callback with either the stream returned or null.
  56     static void capture(CaptureOptions options,
  57                         GetTabMediaCallback callback);
  58
  59     // Returns a list of tabs that have requested capture or are being
  60     // captured, i.e. status != stopped and status != error.
  61     // This allows extensions to inform the user that there is an existing
  62     // tab capture that would prevent a new tab capture from succeeding (or
  63     // to prevent redundant requests for the same tab).
  64     static void getCapturedTabs(GetCapturedTabsCallback callback);
  65   };
  66
  67   interface Events {
  68     // Event fired when the capture status of a tab changes.
  69     // This allows extension authors to keep track of the capture status of
  70     // tabs to keep UI elements like page actions and infobars in sync.
  71     static void onStatusChanged(CaptureInfo info);
  72   };
  73
  74 };