Add DesktopCapturer GetSourceList SelectSource FocusOnSelectedSource functions

webrtc/modules/desktop_capture/desktop_capturer.h

Index: webrtc/modules/desktop_capture/desktop_capturer.h
diff --git a/webrtc/modules/desktop_capture/desktop_capturer.h b/webrtc/modules/desktop_capture/desktop_capturer.h
index d758946b843d1451189f053b8bf642e2adc5867f..dae3709e04a43437ff4dd67225629d9546959658 100644
--- a/webrtc/modules/desktop_capture/desktop_capturer.h
+++ b/webrtc/modules/desktop_capture/desktop_capturer.h
@@ -12,8 +12,11 @@
 #define WEBRTC_MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_
 
 #include <stddef.h>
+#include <stdint.h>
 
 #include <memory>
+#include <string>
+#include <vector>
 
 #include "webrtc/modules/desktop_capture/desktop_frame.h"
 #include "webrtc/modules/desktop_capture/desktop_capture_types.h"
@@ -21,6 +24,7 @@
 
 namespace webrtc {
 
+class DesktopCaptureOptions;
 class DesktopFrame;
 
 // Abstract interface for screen and window capturers.
@@ -53,7 +57,43 @@ class DesktopCapturer {
     virtual ~Callback() {}
   };
 
-  virtual ~DesktopCapturer() {}
+  enum class SourceType {
+    // The source represents a window.
+    WINDOW,
+    // The source represents a screen.
+    SCREEN,
+  };
+
+  typedef webrtc::ScreenId ScreenId;
+  typedef webrtc::WindowId WindowId;
+  typedef intptr_t SourceId;
+
+  struct Source {
+    // Whether this source represents a window or a screen.
+    SourceType type;

[Sergey Ulanov, 2016/10/28 15:53:21]

I don't think we need this field here or SourceType enum. They would be easy to
add in the future if necessary.

[Hzj_jie, 2016/10/28 22:03:53]

I reconsidered this design, and, yes, the SourceId is meaningful only to the
DesktopCapturer returns it. i.e. ScreenCapturerWinDirectx uses a 0-based index
to represent screens, while ScreenCapturerWinGdi uses an index managed by
Windows. i.e. Using a Source coming from one DesktopCapturer to another is
meaningless anyway.

+    // |type| + |id| can identity a unique source in the system.
+    SourceId id;
+    // Title of the window or screen in UTF-8 encoding, maybe empty. This field
+    // should not be used to identify a source.
+    std::string title;
+
+    // The WindowId, if type is SourceType::WINDOW, otherwise undefined.
+    WindowId window_id() const;
+    // The ScreenId, if type is SourceType::SCREEN, otherwise undefined.
+    ScreenId screen_id() const;

[Sergey Ulanov, 2016/10/28 15:53:22]

I don't see a case when these fields can be useful. Just id and title should be
enough.

[Hzj_jie, 2016/10/28 22:03:53]

Done.

+
+    bool operator<(const Source& other) const;
+    bool operator>(const Source& other) const;
+    bool operator==(const Source& other) const;
+    bool operator!=(const Source& other) const;

[Sergey Ulanov, 2016/10/28 15:53:22]

Why do we need these operators? Their behavior is not what one might expect
(they ignore title), so I'd prefer not adding them at all. 

[Hzj_jie, 2016/10/28 22:03:53]

These operators are for comparing one Source to another if we plan to use
SourceType. Since SourceType is removed, these operators should also be removed.

+
+    static Source NewWindow(WindowId id, const std::string& title);
+    static Source NewScreen(ScreenId id);
+  };
+
+  typedef std::vector<Source> SourceList;
+
+  virtual ~DesktopCapturer();
 
   // Called at the beginning of a capturing session. |callback| must remain
   // valid until capturer is destroyed.
@@ -65,7 +105,7 @@ class DesktopCapturer {
   // Shared memory is currently supported only by some DesktopCapturer
   // implementations.
   virtual void SetSharedMemoryFactory(
-      std::unique_ptr<SharedMemoryFactory> shared_memory_factory) {}
+      std::unique_ptr<SharedMemoryFactory> shared_memory_factory);
 
   // Captures next frame, and involve callback provided by Start() function.
   // Pending capture requests are canceled when DesktopCapturer is deleted.
@@ -74,7 +114,25 @@ class DesktopCapturer {
   // Sets the window to be excluded from the captured image in the future
   // Capture calls. Used to exclude the screenshare notification window for
   // screen capturing.
-  virtual void SetExcludedWindow(WindowId window) {}
+  virtual void SetExcludedWindow(WindowId window);
+
+  // TODO(zijiehe): Following functions should be pure virtual. The default
+  // implementations are for backward compatibility only. Remove default
+  // implementations once all DesktopCapturer implementations in Chromium have
+  // implemented these functions.
+
+  // Gets a list of sources current capturer supports. Returns false in case of
+  // a failure.
+  virtual bool GetSourceList(SourceList* sources);
+
+  // Selects a source to be captured. Returns false in case of a failure (e.g.
+  // if there is no source with the specified type and id.)
+  virtual bool SelectSource(const Source& source);
+
+  // Brings the selected source to the front and sets the input focus on it.
+  // Returns false in case of a failure or no source has been selected or the
+  // implementation does not support this functionality.
+  virtual bool FocusOnSelectedSource();
 };
 
 }  // namespace webrtc