Implement Chrome Extension TabCapture API.

chrome/common/extensions/api/experimental_tab_capture.idl

+// Copyright (c) 2012 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.
+
+// An API for tab media streams.
+
+namespace experimental.tabCapture {

[Aaron Boodman, 2012/10/04 07:21:43]

Don't make this experimental. Make it a real API, but use
_permission_features.json to restrict it to 'trunk'.

It may also be useful to add the ability to c/b/extensions/features/feature.cc
to restrict to command line flags. Then you could add a command line flag and
require that to be set too.

We're trying to reduce our usage of 'experimental'. It has so many things in it,
and people turn it on to access one, but it gives access to them all.

[justinlin, 2012/10/08 09:58:31]

Done. By command-line do you mean like one of the flags in about:flags, or
something that can only be enabled by giving the command line flag on startup?

+
+  enum TabCaptureState {
+    requested,
+    cancelled,
+    pending,
+    active,
+    stopped,
+    error
+  };
+
+  dictionary CaptureInfo {
+    // The id of the tab whose status changed.
+    long tabId;
+
+    // The new capture status of the tab.
+    TabCaptureState status;
+  };
+
+  dictionary CaptureOptions {
+    boolean? audio;
+    boolean? video;
+  };
+
+  callback GetTabMediaCallback =
+      void ([instanceOf=LocalMediaStream] optional object stream);
+
+  callback GetCapturedTabsCallback =
+      void (CaptureInfo[] result);
+
+  interface Functions {
+    // Captures the visible area of the tab with the given tabId.
+    // Extensions must have the host permission for the given tab as well as
+    // the "tabs" permission to use this method.

[Aaron Boodman, 2012/10/04 07:21:43]

Why do they need the 'tabs' permission? The tabs permission grants access to the
browsing activity of the user. I don't think that's what this API does (unless
it persists across navigations?)

[justinlin, 2012/10/08 09:58:31]

It does persist across navigations. Added this permission check in the code.

+    // |tabId| : The tabId of the tab to capture.  Defaults to the active tab.
+    // |options| : Configures the returned media stream.
+    // |callback| : Callback with either the stream returned or null.
+    static void getTabMedia(optional long tabId,

[Aaron Boodman, 2012/10/04 07:21:43]

Maybe just name this begin()? or capture()?

[justinlin, 2012/10/11 07:30:13]

Done. I think I prefer capture() because begin() sounds like it implies this can
only be called once to me.

+                            optional CaptureOptions options,
+                            GetTabMediaCallback callback);
+
+    // Returns a list of tabs that have requested capture or are being
+    // captured, i.e. status != stopped and status != cancelled.
+    // This allows extensions to inform the user that there is an existing
+    // tab capture that would prevent a new tab capture from succeeding (or
+    // to prevent redundant requests for the same tab).
+    static void getCapturedTabs(GetCapturedTabsCallback callback);
+
+  };
+
+  interface Events {
+    // Event fired when the capture status of a tab changes.
+    // This allows extension authors to keep track of the capture status of
+    // tabs to keep UI elements like page actions and infobars in sync.
+    static void onTabCaptured(CaptureInfo info);

[Aaron Boodman, 2012/10/04 07:21:43]

Seems like name should be something like onStatusChange then.

[justinlin, 2012/10/11 07:30:13]

Done.

+  };
+
+};