Add DesktopCapturer GetSourceList SelectSource FocusOnSelectedSource functions

webrtc/modules/desktop_capture/desktop_capturer.h

 /*
  *  Copyright (c) 2013 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
 #ifndef WEBRTC_MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_
 #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"
 #include "webrtc/modules/desktop_capture/shared_memory.h"
 
 namespace webrtc {
 
+class DesktopCaptureOptions;
 class DesktopFrame;
 
 // Abstract interface for screen and window capturers.
 class DesktopCapturer {
  public:
   enum class Result {
     // The frame was captured successfully.
     SUCCESS,
 
     // There was a temporary error. The caller should continue calling
@@ skipping 12 matching lines @@
    public:
     // Called after a frame has been captured. |frame| is not nullptr if and
     // only if |result| is SUCCESS.
     virtual void OnCaptureResult(Result result,
                                  std::unique_ptr<DesktopFrame> frame) = 0;
 
    protected:
     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.
   virtual void Start(Callback* callback) = 0;
 
   // Sets SharedMemoryFactory that will be used to create buffers for the
   // captured frames. The factory can be invoked on a thread other than the one
   // where CaptureFrame() is called. It will be destroyed on the same thread.
   // 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.
   virtual void CaptureFrame() = 0;
 
   // 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
 
 #endif  // WEBRTC_MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_