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

chrome/browser/extensions/api/tab_capture/offscreen_presentation.h

 // Copyright 2015 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.
 
 #ifndef CHROME_BROWSER_EXTENSIONS_API_TAB_CAPTURE_OFFSCREEN_PRESENTATION_H_
 #define CHROME_BROWSER_EXTENSIONS_API_TAB_CAPTURE_OFFSCREEN_PRESENTATION_H_
 
 #include <string>
 #include <vector>
 
 #include "base/memory/scoped_vector.h"
 #include "base/time/time.h"
 #include "base/timer/timer.h"
 #include "content/public/browser/web_contents_delegate.h"
 #include "content/public/browser/web_contents_observer.h"
 #include "content/public/browser/web_contents_user_data.h"
 #include "ui/gfx/geometry/size.h"
 
 class Profile;
 
 namespace extensions {
 
+// TODO(miu): This file and classes should be renamed, as this implementation
+// has expanded in scope to be used for all off-screen tabs.
+
 class OffscreenPresentation;  // Forward declaration.  See below.
 
 // Creates, owns, and manages all OffscreenPresentation instances created by the
 // same extension background page.  When the extension background page's
 // WebContents is about to be destroyed, its associated
 // OffscreenPresentationsOwner and all of its OffscreenPresentation instances
 // are destroyed.
 //
 // Usage:
 //
 //   OffscreenPresentationsOwner::Get(extension_contents)
-//       ->FindOrStartPresentation(start_url, presentation_id, size);
+//       ->StartPresentation(start_url, presentation_id, size);
 //
 // This class operates exclusively on the UI thread and so is not thread-safe.
 class OffscreenPresentationsOwner
     : protected content::WebContentsUserData<OffscreenPresentationsOwner> {
  public:
   ~OffscreenPresentationsOwner() override;
 
   // Returns the OffscreenPresentationsOwner instance associated with the given
   // extension background page's WebContents.  Never returns nullptr.
   static OffscreenPresentationsOwner* Get(
       content::WebContents* extension_web_contents);
 
-  // Find a presentation, keyed by |start_url| and |presentation_id|.  If found,
-  // return it.  Otherwise, instantiate a new one and return that.  If too many
-  // presentations have already been started, this method returns nullptr.
-  OffscreenPresentation* FindOrStartPresentation(
+  // Instantiate a new off-screen tab, navigate it to |start_url|, and register
+  // it with the presentation router using |presentation_id| (if a non-empty
+  // string).  If too many off-screen tabs have already been started, this
+  // method returns nullptr.
+  OffscreenPresentation* StartPresentation(
       const GURL& start_url,
-      const std::string& presentation_id,
+      const std::string& optional_presentation_id,
       const gfx::Size& initial_size);
 
  protected:
   friend class OffscreenPresentation;
 
   // Accessor to the extension background page's WebContents.
   content::WebContents* extension_web_contents() const {
     return extension_web_contents_;
   }
 
   // Shuts down and destroys the |presentation|.
   void ClosePresentation(OffscreenPresentation* presentation);
 
  private:
   friend class content::WebContentsUserData<OffscreenPresentationsOwner>;
 
   explicit OffscreenPresentationsOwner(content::WebContents* contents);
 
-  // Returns the OffscreenPresentation that matches the given |start_url| and
-  // |presentation_id|, or nullptr if not found.
-  OffscreenPresentation* FindPresentation(
-      const GURL& start_url, const std::string& presentation_id) const;
-
   content::WebContents* const extension_web_contents_;
   ScopedVector<OffscreenPresentation> presentations_;
 
   DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationsOwner);
 };
 
 // Owns and controls a WebContents instance containing a presentation page.
 // Since the presentation page does not interact with the user in any direct
 // way, the WebContents is not attached to any Browser window/UI, and all input
 // and focusing capabilities are blocked.
@@ skipping 125 matching lines @@
   // This is false until after the Start() method is called, and capture of the
   // |presentation_web_contents_| is first detected.
   bool content_capture_was_detected_;
 
   DISALLOW_COPY_AND_ASSIGN(OffscreenPresentation);
 };
 
 }  // namespace extensions
 
 #endif  // CHROME_BROWSER_EXTENSIONS_API_TAB_CAPTURE_OFFSCREEN_PRESENTATION_H_