getUserMeida: report device starting states

media/capture/video/video_capture_device.h

 // Copyright (c) 2012 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.
 //
 // VideoCaptureDevice is the abstract base class for realizing video capture
 // device support in Chromium. It provides the interface for OS dependent
 // implementations.
 // The class is created and functions are invoked on a thread owned by
 // VideoCaptureManager. Capturing is done on other threads, depending on the OS
 // specific implementation.
@@ skipping 66 matching lines @@
 };
 
 class CAPTURE_EXPORT VideoCaptureDevice
     : public VideoFrameConsumerFeedbackObserver {
  public:
 
   // Interface defining the methods that clients of VideoCapture must have. It
   // is actually two-in-one: clients may implement OnIncomingCapturedData() or
   // ReserveOutputBuffer() + OnIncomingCapturedVideoFrame(), or all of them.
   // All clients must implement OnError().
+  // All clients must implement OnStarted(). Captured frames can be delivered
+  // as soon as AllocateAndStart() is called, despite of OnStarted processing.

[chfremer, 2017/02/22 19:13:58]

As discussed offline, the "All clients must implement ..." is not meaningful,
since the language already enforces that purely virtual methods must be
implemented. Please remove that part.

The "despite of OnStarted processing" part is hard to understand. I would write
something like this: 
All methods may be called as soon as AllocateAndStart() of the corresponding
VideoCaptureDevice is invoked. The methods for buffer reservation and frame
delivery may be called from arbitrary threads but are guaranteed to be called
non-concurrently. The status reporting methods (OnStarted, OnLog, OnError) may
be called concurrently.

[braveyao, 2017/02/23 00:06:26]

Done.

   class CAPTURE_EXPORT Client {
    public:
     // Move-only type representing access to a buffer handle as well as
     // read-write permission to its contents.
     class CAPTURE_EXPORT Buffer {
      public:
       // Destructor-only interface for encapsulating scoped access permission to
       // a Buffer.
       class CAPTURE_EXPORT ScopedAccessPermission {
        public:
@@ skipping 110 matching lines @@
     // be StopAndDeAllocate()-ed. |reason| is a text description of the error.
     virtual void OnError(const tracked_objects::Location& from_here,
                          const std::string& reason) = 0;
 
     // VideoCaptureDevice requests the |message| to be logged.
     virtual void OnLog(const std::string& message) {}
 
     // Returns the current buffer pool utilization, in the range 0.0 (no buffers
     // are in use by producers or consumers) to 1.0 (all buffers are in use).
     virtual double GetBufferPoolUtilization() const = 0;
+
+    // VideoCaptureDevice reports it's successfully started.
+    // This method may be called either synchronously from an invocation of
+    // VideoCaptureDevice::AllocateAndStart() or asynchronously from any thread
+    // after AllocateAndStart() has returned.

[chfremer, 2017/02/22 19:13:58]

According to the latest design, it may actually be called even _before_
AllocateAndStart() has returned. It may be called as soon as AllocateAndStart()
is invoked.

And since we are now explaining the contract of when this may be called in the
class description (at the top), we no longer need to specify it here. Please
remove.

[braveyao, 2017/02/23 00:06:26]

Done.

+    virtual void OnStarted() = 0;
   };
 
   ~VideoCaptureDevice() override;
 
   // Prepares the video capturer for use. StopAndDeAllocate() must be called
   // before the object is deleted.
   virtual void AllocateAndStart(const VideoCaptureParams& params,
                                 std::unique_ptr<Client> client) = 0;
 
   // In cases where the video capturer self-pauses (e.g., a screen capturer
@@ skipping 75 matching lines @@
 
  private:
   // Gets the power line frequency from the current system time zone if this is
   // defined, otherwise returns 0.
   PowerLineFrequency GetPowerLineFrequencyForLocation() const;
 };
 
 }  // namespace media
 
 #endif  // MEDIA_CAPTURE_VIDEO_VIDEO_CAPTURE_DEVICE_H_