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 48 matching lines @@
     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);
+
+    // Locates an off-screen presentation tab identified by a starting
+    // |presentationUrl| and |presentationId|.  If not found, one is
+    // automatically created and navigated to |presentationUrl|.  Then, capture
+    // is started.
+    //
+    // Off-screen presentation tabs are used to simulate the rendering of a web
+    // page on a remote device.  This is accomplished by rendering the page
+    // locally and capturing its audio and/or video output into a MediaStream.
+    // Users of this API can then remote the MediaStream (e.g., via WebRTC or
+    // Cast) to a remote playback device.
+    //
+    // Therefore, off-screen presentation 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).  For security reasons, they are isolated in their
+    // own non-shared incognito profile and 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.
+    //
+    // An off-screen presentation tab remains alive until one of three events
+    // occurs: 1. All MediaStreams providing its captured content are closed;
+    // 2. the page being rendered calls window.close(); 3. the extension that
+    // called capturePresentation() is unloaded.
+    //
+    // This is a new, experimental API and may change without notice.  In
+    // addition, it is only available when the browser is run with the
+    // --enable-capture-presentation-api switch.
+    //
+    // |options| : Configures the capture and returned MediaStream.
+    // |callback| : <code>null</code> on error.
+    static void capturePresentation(DOMString presentationUrl,
+                                    DOMString presentationId,
+                                    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);
   };
 
 };