Adds QueryResultManager support class for Media Router Dialog WebUI

chrome/browser/ui/webui/media_router/query_result_manager.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_UI_WEBUI_MEDIA_ROUTER_QUERY_RESULT_MANAGER_H_
+#define CHROME_BROWSER_UI_WEBUI_MEDIA_ROUTER_QUERY_RESULT_MANAGER_H_
+
+#include <map>
+#include <set>
+#include <vector>
+
+#include "base/gtest_prod_util.h"
+#include "base/memory/linked_ptr.h"
+#include "base/observer_list.h"
+#include "base/threading/thread_checker.h"
+#include "chrome/browser/media/router/media_routes_observer.h"
+#include "chrome/browser/media/router/media_sink.h"
+#include "chrome/browser/media/router/media_sinks_observer.h"
+#include "chrome/browser/media/router/media_source.h"
+#include "chrome/browser/ui/webui/media_router/media_cast_mode.h"
+#include "chrome/browser/ui/webui/media_router/media_sink_with_cast_modes.h"
+
+namespace media_router {
+
+class MediaRouter;
+class MediaSinksObserver;
+struct RoutesQueryResult;
+struct SinksQueryResult;
+
+// The Media Router dialog allows the user to initiate casting using one of
+// several actions (each represented by a cast mode).  Each cast mode is
+// associated with a media source.  This class allows the dialog to receive
+// lists of MediaSinks compatible with the cast modes available through the
+// dialog.
+//
+// Typical use:
+//
+//   QueryResultManager::Observer* observer = ...;
+//   QueryResultManager result_manager(router);
+//   result_manager.AddObserver(observer);
+//   result_manager.StartSinksQuery(MediaCastMode::DEFAULT,
+//       ForPresentationUrl("http://google.com"));
+//   result_manager.StartSinksQuery(MediaCastMode::TAB_MIRROR,
+//       ForTabMediaSource(123));
+//   ...
+//   [Updates will be received by observer via OnResultsUpdated()]
+//   ...
+//   [When info on MediaSource is needed, i.e. when requesting route for a mode]
+//   CastModeSet cast_modes;
+//   result_manager.GetSupportedCastModes(&cast_modes);
+//   [Logic to select a MediaCastMode from the set]
+//   MediaSource source = result_manager.GetSourceForCastMode(
+//       MediaCastMode::TAB_MIRROR);
+//   if (!source.Empty()) {
+//     ...
+//   }
+//
+// Not thread-safe.

[Bernhard Bauer, 2015/05/08 08:34:33]

Nit: Thread safety (or lack thereof) comes in so many different flavors, it
might be more useful to specifically note the threading constraints. In this
case, I think the class should always be used on the same thread?

Alternatively, you could inherit from base::NonThreadSafe, which will give you a
protected CalledOnValidThread() method and basically express the same thing.

[mark a. foltz, 2015/05/12 06:23:15]

That's correct. I clarified the comment.
The class uses a base::ThreadChecker to verify thread usage, this is the pattern
we have been using in media router related classes.

+class QueryResultManager {
+ public:
+  class Observer {

[Bernhard Bauer, 2015/05/08 08:34:34]

Optional: Instead of a single-method Observer interface, you could also use
base::CallbackList<>.

[mark a. foltz, 2015/05/12 06:23:15]

Thanks I was not aware of that.  It looks like CallbackList is good for classes
that have several different subscriber implementations and want very loose
coupling between the two.  In this case we have one implementation and the
Observer interface makes the collaboration obvious via public inheritance.

My preference is to keep the current pattern; if you feel strongly I would
appreciate reasons why CallbackList is preferable.

[Bernhard Bauer, 2015/05/12 09:34:34]

I definitely don't feel strongly. Personally, I just prefer Callback over a
single-method interface, as they are basically isomorphic, and CallbackList lets
you do registration and unregistration with a single method, so in total
Callback + CallbackList is less code.

[mark a. foltz, 2015/05/12 19:05:26]

Acknowledged.

+   public:
+    virtual ~Observer() {}
+
+    // Updated results have been received.
+    // |sinks|: List of sinks and the cast modes they are compatible with.
+    virtual void OnResultsUpdated(
+        const std::vector<MediaSinkWithCastModes>& sinks) = 0;
+  };
+
+  explicit QueryResultManager(MediaRouter* media_router);
+  ~QueryResultManager();
+
+  // Adds/removes an observer that is notified with query results.
+  void AddObserver(Observer* observer);
+  void RemoveObserver(Observer* observer);
+
+  // Requests a list of MediaSinks compatible with |source| for |cast_mode|.
+  // Results are sent to all observers registered with AddObserver().
+  //
+  // May start a new query in the Media Router for the registered source if
+  // there is no existing query for it.  If there is an existing query for
+  // |cast_mode|, it is stopped.
+  //
+  // If |source| is empty, no new queries are begun.
+  void StartSinksQuery(MediaCastMode cast_mode, const MediaSource& source);
+
+  // Stops notifying observers for |cast_mode|.
+  void StopSinksQuery(MediaCastMode cast_mode);
+
+  // Gets the set of cast modes that are being actively queried. |cast_mode_set|
+  // should be empty.
+  void GetSupportedCastModes(CastModeSet* cast_modes) const;
+
+  // Returns the MediaSource registered for |cast_mode|.  Returns an empty
+  // MediaSource if there is none.
+  MediaSource GetSourceForCastMode(MediaCastMode cast_mode) const;
+
+ private:
+  FRIEND_TEST_ALL_PREFIXES(QueryResultManagerTest, Observers);
+  FRIEND_TEST_ALL_PREFIXES(QueryResultManagerTest, StartRoutesDiscovery);
+  FRIEND_TEST_ALL_PREFIXES(QueryResultManagerTest, MultipleQueries);
+
+  // MediaSinkObserver that propagates results back to |this|.
+  // An instance of this class is associated with each registered MediaCastMode.
+  class CastModeMediaSinksObserver : public MediaSinksObserver {

[Bernhard Bauer, 2015/05/08 08:34:33]

Can you define this class in the .cc file and just forward-declare it here?

[mark a. foltz, 2015/05/12 06:23:15]

Done.

+   public:
+    CastModeMediaSinksObserver(MediaCastMode cast_mode,
+                               const MediaSource& source,
+                               MediaRouter* router,
+                               QueryResultManager* result_manager);
+    ~CastModeMediaSinksObserver() override;
+
+    // MediaSinksObserver
+    void OnSinksReceived(const std::vector<MediaSink>& result) override;
+
+    // Returns the most recent sink IDs that were passed to |OnSinksReceived|.
+    void GetLatestSinkIds(std::vector<MediaSinkId>* sink_ids) const;
+
+    MediaCastMode cast_mode() const { return cast_mode_; }
+
+   private:
+    MediaCastMode cast_mode_;
+    std::vector<MediaSinkId> latest_sink_ids_;
+    QueryResultManager* result_manager_;
+  };
+
+  // Sets the media source for |cast_mode|.
+  void SetSourceForCastMode(MediaCastMode cast_mode, const MediaSource& source);
+
+  // Stops and destroys the CastModeMediaSinksObserver for |cast_mode|.
+  void RemoveObserverForCastMode(MediaCastMode cast_mode);
+
+  // Returns true if the |entry|'s sink is compatible with at least one cast
+  // mode.
+  bool IsValid(const MediaSinkWithCastModes& entry) const;
+
+  // Modifies the current set of results with |result| associated with
+  // |cast_mode|.
+  void UpdateWithSinksQueryResult(MediaCastMode cast_mode,
+                                  const std::vector<MediaSink>& result);
+
+  // Notifies observers that results have been updated.
+  void NotifyOnResultsUpdated();
+
+  // MediaSinksObservers that listens for compatible MediaSink updates.
+  // Each observer is associated with a MediaCastMode. Results received by
+  // observers are propagated back to this class.
+  std::map<MediaCastMode, linked_ptr<CastModeMediaSinksObserver>>

[Bernhard Bauer, 2015/05/08 08:34:33]

Can you avoid using linked_ptr? Its use is somwhat discouraged. For maps with
owwning semantics, you can use base::ScopedPtrHashMap.

[mark a. foltz, 2015/05/12 06:23:15]

Is there a "scoped" replacement for std::map?  I did not see any landed in
crbug.com/137767 or in base/memory.

[Bernhard Bauer, 2015/05/12 09:34:34]

No, there's only one for hash_map so far (for whatever reason).

[mark a. foltz, 2015/05/12 19:05:26]

The ScopedPtrHashMap is really a different API from std::map and would require
extra code to use (like defining hash functions).  I'm happy to make the change
when it makes the code simpler to do so.  Added a TODO.

+      sinks_observers_;
+
+  // Holds registrations of MediaSources for cast modes.
+  std::map<MediaCastMode, MediaSource> cast_mode_sources_;
+
+  // Holds all known sinks and their associated cast modes.
+  std::map<MediaSinkId, MediaSinkWithCastModes> all_sinks_;
+
+  // Registered observers.
+  ObserverList<Observer> observers_;
+
+  // Not owned by this object.
+  MediaRouter* router_;
+
+  base::ThreadChecker thread_checker_;
+
+  DISALLOW_COPY_AND_ASSIGN(QueryResultManager);
+};
+
+}  // namespace media_router
+
+#endif  // CHROME_BROWSER_UI_WEBUI_MEDIA_ROUTER_QUERY_RESULT_MANAGER_H_