[Presentation API] 1-UA presentation support + presenter APIs.

content/public/browser/presentation_service_delegate.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 CONTENT_PUBLIC_BROWSER_PRESENTATION_SERVICE_DELEGATE_H_
 #define CONTENT_PUBLIC_BROWSER_PRESENTATION_SERVICE_DELEGATE_H_
 
 #include <string>
 #include <vector>
 
 #include "base/callback.h"
 #include "base/memory/scoped_ptr.h"
 #include "base/memory/scoped_vector.h"
 #include "content/common/content_export.h"
 #include "content/public/browser/presentation_session.h"
 #include "content/public/browser/presentation_session_message.h"
 
 namespace content {
 
 class PresentationScreenAvailabilityListener;
 class PresentationSessionStateListener;
 
 // Param #0: a vector of messages that are received.
 // Param #1: tells the callback handler that it may reuse strings or buffers
 //           in the messages contained within param #0.
 using PresentationSessionMessageCallback = base::Callback<
     void(const ScopedVector<content::PresentationSessionMessage>&, bool)>;
 
+using PresentationReceiverSessionAvailableCallback =
+    base::Callback<void(const content::PresentationSessionInfo*)>;
+
+using SendMessageCallback = base::Callback<void(bool)>;
+
 // An interface implemented by embedders to handle presentation API calls
 // forwarded from PresentationServiceImpl.
 class CONTENT_EXPORT PresentationServiceDelegate {
  public:
   // Observer interface to listen for changes to PresentationServiceDelegate.
   class CONTENT_EXPORT Observer {
    public:
     // Called when the PresentationServiceDelegate is being destroyed.
     virtual void OnDelegateDestroyed() = 0;

[miu, 2015/10/07 21:51:47]

nit: The methods in this interface should probably be defined as no-ops, instead
of forcing subclasses to override all pure virtual methods.  This relates to my
comment below...

[imcheng, 2015/10/10 04:39:44]

Ack. we only have 2 implementations of this and they are different. So I will
keep this for now. See comment below as well.

 
     // Called when the default presentation has been started outside of a
     // Presentation API context (e.g., browser action). This will not be called
     // if the session was created as a result of Presentation API's
     // StartSession()/JoinSession().
     virtual void OnDefaultPresentationStarted(
         const PresentationSessionInfo& session) = 0;
 
    protected:
     virtual ~Observer() {}
   };
 
   using PresentationSessionSuccessCallback =
       base::Callback<void(const PresentationSessionInfo&)>;
   using PresentationSessionErrorCallback =
       base::Callback<void(const PresentationError&)>;
-  using SendMessageCallback = base::Callback<void(bool)>;
 
   virtual ~PresentationServiceDelegate() {}
 
   // Registers an observer associated with frame with |render_process_id|
   // and |render_frame_id| with this class to listen for updates.
   // This class does not own the observer.
   // It is an error to add an observer if there is already an observer for that
   // frame.
   virtual void AddObserver(int render_process_id,
                            int render_frame_id,
@@ skipping 107 matching lines @@
   // Continuously listen for presentation session state changes for a session.
   // Returns true if |listener| is sucessfully registered.
   // |render_process_id|, |render_frame_id|: ID of frame.
   // |session|: Presentation session to listen for state changes.
   // |listener|: The listener to be invoked whenever there is a state change.
   //             Not owned by this class.
   virtual bool ListenForSessionStateChange(
       int render_process_id,
       int render_frame_id,
       content::PresentationSessionStateListener* listener) = 0;
+
+  // Gets a receiver presentation session for the offscreen presentation hosted

[miu, 2015/10/07 21:51:47]

The wording in this comment was a bit confusing to me.  How about:

  Runs |callback| once the receiver becomes available.  |callback| may be run
during this method call (if the receiver is already available), or at some later
time.  |render_process_id| and |render_frame_id| must refer to the main render
frame of an off-screen tab.

BTW--What should happen if a receiver never becomes available?  Is the callback
guaranteed to be run with a nullptr, or never run at all?

[imcheng, 2015/10/10 04:39:44]

Done. If a receiver session never becomes available, the callback will never be
run.

+  // on the offscreen tab containing this frame, or waits until one is
+  // available.
+  // If there is at least one receiver presentation session, |callback| will
+  // be invoked with one of the sessions immediately.
+  // Otherwise, |callback| will be invoked when a receiver presentation session
+  // becomes available.
+  // If the calling frame is not the main frame of an offscreen tab,
+  // |callback| will be invoked with null.
+  virtual void GetPresentationReceiverSession(

[miu, 2015/10/07 21:51:47]

Consider naming this method something like
NotifyWhenReceiverSessionIsAvailable() to make it clear that it's different from
GetPresentationReceiverSessions().

Even better, consider eliminating this method (and ListenForSessionMessages()
and ListenForSessionStateChange()) by adding extra methods to the Observer
interface.  Then, you also won't need all these extra callback typedefs.

[imcheng, 2015/10/10 04:39:44]

Renamed per your suggestion. I am not a fan of the
PresentationServiceDelegate::Observer interface. I think it's clearer to define
the expected behavior yet rather than having an all purpose observer class.

+      int render_process_id,
+      int render_frame_id,
+      const PresentationReceiverSessionAvailableCallback& callback) = 0;
+
+  // Gets all receiver presentation sessions for the offscreen presentation
+  // hosted on the offscreen tab containing this frame.
+  // If the calling frame is not the main frame of an offscreen tab, an empty
+  // vector will be returned.
+  virtual std::vector<content::PresentationSessionInfo>
+  GetPresentationReceiverSessions(int render_process_id,
+                                  int render_frame_id) = 0;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_PRESENTATION_SERVICE_DELEGATE_H_