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, or creates on-demand, an off-screen tab identified by a
+    // |startUrl| and |id|.  When created, the off-screen tab is automatically

[not at google - send to devlin, 2015/09/25 16:56:03]

Where does the id come from?

[miu, 2015/09/25 17:35:32]

This is explained a few sentences later in this paragraph:  ;-)

"|id| can be any client-provided string.  It is used only to disambiguate
off-screen tabs with the same |startUrl|."

Or, am I misunderstanding your question?

[not at google - send to devlin, 2015/09/25 17:42:04]

Yeah I didn't read on, but my follow-up was, it doesn't appear to be used
anywhere.

[miu, 2015/09/25 18:47:54]

See line 268 in tab_capture_api.cc.  It is passed to the
OffscreenPresentationsOwner to search for (or create) an off-screen tab.  You
can think of startUrl+id as the "key" for finding an off-screen tab.

(Side note: I put in a TODO comment to rename the OffscreenPresentation* classes
to OffscreenTab*)

[not at google - send to devlin, 2015/09/25 19:13:24]

ok, 3rd question: can the API generate one itself? why leave it to the
extension?

[miu, 2015/09/25 21:59:17]

As I was answering your question, I'm now thinking we should get rid of the |id|
field.  If we change this API to always create a new off-screen tab (i.e., not
attempt to find an existing one), then there's no need for it.  WDYT?

Otherwise, to answer your question...

I don't think generating these IDs should be the responsibility of this API.  It
does nothing with this |id| field except use it to disambiguate between two
off-screen tabs with the same |startUrl|.  Meaning, if the extension creating
off-screen tabs would never create two tabs with the same |startUrl|, it could
just provide an empty string for the |id| field.

The reason we need this field is that, in the Media Router extension use case,
it can create multiple off-screen tabs with the same |startUrl|, but for
different presentation sessions.  In this case, the presentation session ID
would be used to disambiguate.

[not at google - send to devlin, 2015/09/25 22:29:55]

Yes I'd like to avoid having an ID here. If you want to have reusable tabs then
I'd have this API return a tab ID on creation and make it part of the capture
options if an extension wants to start capturing old tabs. Basically the same as
the foreground tab API.

However in the case of these offscreen tabs, they're closed when the reference
to the stream has been dropped, right? Insofar as I presume once there is no
reference to a stream, it gets closed?

In which case I don't see being able to fetch an existing tab really makes much
sense?

[miu, 2015/09/26 20:40:14]

Done.

However, I forgot to mention there is a second reason we needed the ID field. 
To support the W3C Presentation API use case (via the internal Media Router
extension), we need a way to "register" the off-screen tab's WebContents as a
participant in the presentation session.  After considering several design
alternatives, I decided the cleanest solution is to add this back as an
undocumented |presentationId| field to the CaptureOptions.

Why we need this:
https://codereview.chromium.org/1314413005/diff/40001/chrome/browser/extensio...
 (line 231)

[not at google - send to devlin, 2015/09/30 01:32:11]

I'll reply there.

[miu, 2015/09/30 19:46:38]

Didn't see a comment there.  Does that mean this is okay?

+    // navigated to the given |startUrl|.  Then, capture is started and a
+    // MediaStream is returned via |callback|.  |id| can be any client-provided
+    // string.  It is used only to disambiguate off-screen tabs with the same
+    // |startUrl|.
+    //
+    // 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 dedicated, non-shared off-the-record profile.  Also, it

[not at google - send to devlin, 2015/09/25 22:29:55]

Can we say "sandboxed" instead of "off-the-record"? is that correct? I think
that "off-the-record" may be confused with it runs in an existing off-the-record
profile, or possible the offscreen tabs share a profile.

[miu, 2015/09/26 20:40:14]

Done.

+    // 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 via whitelisting, and

[not at google - send to devlin, 2015/09/25 22:29:55]

whitelisting? This is dev channel now right? The documentation server should
know how to generate that information already.

[miu, 2015/09/26 20:40:14]

I wasn't sure we were ready for dev-channel yet, given the security discussion
that is still going on about use cases where the MediaStream can go to a
destination not directly under the user's control.  I had been planning on
making another CL to turn that on later, once we made more progress.

So, I went ahead and made this change.  However, if you feel it's not yet safe
for dev-channel, I can revert.

[not at google - send to devlin, 2015/09/30 01:32:11]

Makes sense. Just double checking.

+    // may change without notice.
+    //
+    // |options| : Constraints for the capture and returned MediaStream.
+    // |callback| : <code>null</code> on error.
+    static void captureOffscreenTab(DOMString startUrl,
+                                    DOMString id,
+                                    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);
   };
 
 };