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, 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 and navigate it to |start_url|.  The new
+  // tab's main frame will start out with the given |initial_size| in DIP
+  // coordinates.  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 gfx::Size& initial_size);
 
+  // Retrieve an existing instance by its ID.  If not found, this method returns
+  // nullptr.
+  OffscreenPresentation* FindByOffscreenTabId(
+      const std::string& offscreen_tab_id) const;
+
  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;
+  // Returns a unique, random ID that no other OffscreenPresentation has.
+  std::string CreateUniqueRandomId() 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
@@ skipping 12 matching lines @@
 //   3. Automatically, when the extension background page's WebContents is
 //      destroyed.
 //
 // This class operates exclusively on the UI thread and so is not thread-safe.
 class OffscreenPresentation : protected content::WebContentsDelegate,
                               protected content::WebContentsObserver {
  public:
   ~OffscreenPresentation() final;
 
   const GURL& start_url() const { return start_url_; }
-  const std::string& presentation_id() const { return presentation_id_; }
+  const std::string& id() const { return id_; }
 
   // The presentation page's WebContents instance.
   content::WebContents* web_contents() const {
     return presentation_web_contents_.get();
   }
 
  protected:
   friend class OffscreenPresentationsOwner;
 
   OffscreenPresentation(OffscreenPresentationsOwner* owner,
@@ skipping 59 matching lines @@
   // Called by |capture_poll_timer_| to automatically destroy this
   // OffscreenPresentation when the capturer count returns to zero.
   void DieIfContentCaptureEnded();
 
   OffscreenPresentationsOwner* const owner_;
 
   // The starting URL for this presentation, which may or may not match the
   // current WebContents URL if navigations have occurred.
   const GURL start_url_;
 
-  // The presentation ID used to help uniquely identify this instance.
-  const std::string presentation_id_;
+  // An ID used to uniquely identify this instance.
+  const std::string id_;
 
   // A non-shared off-the-record profile based on the profile of the extension
   // background page.
   const scoped_ptr<Profile> profile_;
 
   // The WebContents containing the offscreen presentation page.
   scoped_ptr<content::WebContents> presentation_web_contents_;
 
   // The time at which Start() finished creating |presentation_web_contents_|.
   base::TimeTicks start_time_;
@@ skipping 12 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_