New tabCapture.captureOffscreenTab API, initially for Presentation API 1UA mode

chrome/common/extensions/api/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.
 
 // Use the <code>chrome.tabCapture</code> API to interact with tab media
 // streams.
 namespace tabCapture {
 
   enum TabCaptureState {
     pending,
@@ skipping 21 matching lines @@
     object? _optional;
   };
 
   // Whether we are requesting tab video and/or audio and the
   // MediaTrackConstraints that should be set for these streams.
   dictionary CaptureOptions {
     boolean? audio;
     boolean? video;
     MediaStreamConstraint? audioConstraints;
     MediaStreamConstraint? videoConstraints;
+    [nodoc] DOMString? presentationId;
   };
 
   callback GetTabMediaCallback =
       void ([instanceOf=LocalMediaStream] object stream);
 
   callback GetCapturedTabsCallback = void (CaptureInfo[] result);
 
   interface Functions {
     // Captures the visible area of the currently active tab.  Capture can
     // only be started on the currently active tab after the extension has been
     // <em>invoked</em>.  Capture is maintained across page navigations within
     // the tab, and stops when the tab is closed, or the media stream is closed
     // by the extension.
     //
     // |options| : Configures the returned media stream.
     // |callback| : Callback with either the tab capture stream or
     //   <code>null</code>.
     static void capture(CaptureOptions options,
                         GetTabMediaCallback callback);
 
     // Returns a list of tabs that have requested capture or are being
     // captured, i.e. status != stopped and status != error.
     // 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).
     // |callback| : Callback invoked with CaptureInfo[] for captured tabs.
     static void getCapturedTabs(GetCapturedTabsCallback callback);
+
+    // Creates an off-screen tab and navigates it to the given |startUrl|.
+    // Then, capture is started and a MediaStream is returned via |callback|.
+    //
+    // Off-screen tabs are isolated from the user's normal browser experience.
+    // They do not show up in the browser window or tab strip, nor are they
+    // visible to extensions (e.g., via the chrome.tabs.* APIs).
+    //
+    // An off-screen tab remains alive until one of three events occurs: 1. All
+    // MediaStreams providing its captured content are closed; 2. the page
+    // self-closes (e.g., via window.close()); 3. the extension that called
+    // captureOffscreenTab() is unloaded.
+    //
+    // Sandboxing: The off-screen tab does not have any access whatsoever to the
+    // local user profile (including cookies, HTTP auth, etc.).  Instead, it is
+    // provided its own sandboxed profile.  Also, it cannot access any
+    // interactive resources such as keyboard/mouse input, media recording
+    // devices (e.g., web cams), copy/paste to/from the system clipboard, etc.
+    //
+    // Note: This is a new API, currently only available in Canary/Dev channel,
+    // and may change without notice.
+    //
+    // |options| : Constraints for the capture and returned MediaStream.
+    // |callback| : <code>null</code> on error.
+    static void captureOffscreenTab(DOMString startUrl,
+                                    CaptureOptions options,
+                                    GetTabMediaCallback 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 in sync.
     // |info| : CaptureInfo with new capture status for the tab.
     static void onStatusChanged(CaptureInfo info);
   };
 
 };