src/content/public/common/media_stream_request.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CONTENT_PUBLIC_COMMON_MEDIA_STREAM_REQUEST_H_
   6 #define CONTENT_PUBLIC_COMMON_MEDIA_STREAM_REQUEST_H_
   7
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/basictypes.h"
  13 #include "base/callback_forward.h"
  14 #include "base/memory/scoped_ptr.h"
  15 #include "content/common/content_export.h"
  16 #include "ui/gfx/native_widget_types.h"
  17 #include "url/gurl.h"
  18
  19 namespace content {
  20
  21 // Types of media streams.
  22 enum MediaStreamType {
  23   MEDIA_NO_SERVICE = 0,
  24
  25   // A device provided by the operating system (e.g., webcam input).
  26   MEDIA_DEVICE_AUDIO_CAPTURE,
  27   MEDIA_DEVICE_VIDEO_CAPTURE,
  28
  29   // Mirroring of a browser tab.
  30   MEDIA_TAB_AUDIO_CAPTURE,
  31   MEDIA_TAB_VIDEO_CAPTURE,
  32
  33   // Desktop media sources.
  34   MEDIA_DESKTOP_VIDEO_CAPTURE,
  35
  36   // Capture system audio (post-mix loopback stream).
  37   //
  38   // TODO(sergeyu): Replace with MEDIA_DESKTOP_AUDIO_CAPTURE.
  39   MEDIA_LOOPBACK_AUDIO_CAPTURE,
  40
  41   // This is used for enumerating audio output devices.
  42   // TODO(grunell): Output isn't really a part of media streams. Device
  43   // enumeration should be decoupled from media streams and related code.
  44   MEDIA_DEVICE_AUDIO_OUTPUT,
  45
  46   NUM_MEDIA_TYPES
  47 };
  48
  49 // Types of media stream requests that can be made to the media controller.
  50 enum MediaStreamRequestType {
  51   MEDIA_DEVICE_ACCESS = 0,
  52   MEDIA_GENERATE_STREAM,
  53   MEDIA_ENUMERATE_DEVICES,
  54   MEDIA_OPEN_DEVICE  // Only used in requests made by Pepper.
  55 };
  56
  57 // Facing mode for video capture.
  58 enum VideoFacingMode {
  59   MEDIA_VIDEO_FACING_NONE = 0,
  60   MEDIA_VIDEO_FACING_USER,
  61   MEDIA_VIDEO_FACING_ENVIRONMENT,
  62
  63   NUM_MEDIA_VIDEO_FACING_MODE
  64 };
  65
  66 // Elements in this enum should not be deleted or rearranged; the only
  67 // permitted operation is to add new elements before NUM_MEDIA_REQUEST_RESULTS.
  68 enum MediaStreamRequestResult {
  69   MEDIA_DEVICE_OK = 0,
  70   MEDIA_DEVICE_PERMISSION_DENIED = 1,
  71   MEDIA_DEVICE_PERMISSION_DISMISSED = 2,
  72   MEDIA_DEVICE_INVALID_STATE = 3,
  73   MEDIA_DEVICE_NO_HARDWARE = 4,
  74   MEDIA_DEVICE_INVALID_SECURITY_ORIGIN = 5,
  75   MEDIA_DEVICE_TAB_CAPTURE_FAILURE = 6,
  76   MEDIA_DEVICE_SCREEN_CAPTURE_FAILURE = 7,
  77   MEDIA_DEVICE_CAPTURE_FAILURE = 8,
  78   MEDIA_DEVICE_CONSTRAINT_NOT_SATISFIED = 9,
  79   MEDIA_DEVICE_TRACK_START_FAILURE = 10,
  80   MEDIA_DEVICE_NOT_SUPPORTED = 11,
  81   MEDIA_DEVICE_FAILED_DUE_TO_SHUTDOWN = 12,
  82   NUM_MEDIA_REQUEST_RESULTS
  83 };
  84
  85 // Convenience predicates to determine whether the given type represents some
  86 // audio or some video device.
  87 CONTENT_EXPORT bool IsAudioInputMediaType(MediaStreamType type);
  88 CONTENT_EXPORT bool IsVideoMediaType(MediaStreamType type);
  89
  90 // TODO(xians): Change the structs to classes.
  91 // Represents one device in a request for media stream(s).
  92 struct CONTENT_EXPORT MediaStreamDevice {
  93   MediaStreamDevice();
  94
  95   MediaStreamDevice(
  96       MediaStreamType type,
  97       const std::string& id,
  98       const std::string& name);
  99
 100   MediaStreamDevice(
 101       MediaStreamType type,
 102       const std::string& id,
 103       const std::string& name,
 104       int sample_rate,
 105       int channel_layout,
 106       int frames_per_buffer);
 107
 108   ~MediaStreamDevice();
 109
 110   bool IsEqual(const MediaStreamDevice& second) const;
 111
 112   // The device's type.
 113   MediaStreamType type;
 114
 115   // The device's unique ID.
 116   std::string id;
 117
 118   // The facing mode for video capture device.
 119   VideoFacingMode video_facing;
 120
 121   // The device id of a matched output device if any (otherwise empty).
 122   // Only applicable to audio devices.
 123   std::string matched_output_device_id;
 124
 125   // The device's "friendly" name. Not guaranteed to be unique.
 126   std::string name;
 127
 128   // Contains properties that match directly with those with the same name
 129   // in media::AudioParameters.
 130   struct AudioDeviceParameters {
 131     AudioDeviceParameters()
 132         : sample_rate(), channel_layout(), frames_per_buffer(), effects() {
 133     }
 134
 135     AudioDeviceParameters(int sample_rate, int channel_layout,
 136         int frames_per_buffer)
 137         : sample_rate(sample_rate),
 138           channel_layout(channel_layout),
 139           frames_per_buffer(frames_per_buffer),
 140           effects() {
 141     }
 142
 143     // Preferred sample rate in samples per second for the device.
 144     int sample_rate;
 145
 146     // Preferred channel configuration for the device.
 147     // TODO(henrika): ideally, we would like to use media::ChannelLayout here
 148     // but including media/base/channel_layout.h violates checkdeps rules.
 149     int channel_layout;
 150
 151     // Preferred number of frames per buffer for the device.  This is filled
 152     // in on the browser side and can be used by the renderer to match the
 153     // expected browser side settings and avoid unnecessary buffering.
 154     // See media::AudioParameters for more.
 155     int frames_per_buffer;
 156
 157     // See media::AudioParameters::PlatformEffectsMask.
 158     int effects;
 159   };
 160
 161   // These below two member variables are valid only when the type of device is
 162   // audio (i.e. IsAudioInputMediaType returns true).
 163
 164   // Contains the device properties of the capture device.
 165   AudioDeviceParameters input;
 166
 167   // If the capture device has an associated output device (e.g. headphones),
 168   // this will contain the properties for the output device.  If no such device
 169   // exists (e.g. webcam w/mic), then the value of this member will be all
 170   // zeros.
 171   AudioDeviceParameters matched_output;
 172 };
 173
 174 class CONTENT_EXPORT MediaStreamDevices
 175     : public std::vector<MediaStreamDevice> {
 176  public:
 177   MediaStreamDevices();
 178   MediaStreamDevices(size_t count, const MediaStreamDevice& value);
 179
 180   // Looks for a MediaStreamDevice based on its ID.
 181   // Returns NULL if not found.
 182   const MediaStreamDevice* FindById(const std::string& device_id) const;
 183 };
 184
 185 typedef std::map<MediaStreamType, MediaStreamDevices> MediaStreamDeviceMap;
 186
 187 // Represents a request for media streams (audio/video).
 188 // TODO(vrk): Decouple MediaStreamDevice from this header file so that
 189 // media_stream_options.h no longer depends on this file.
 190 // TODO(vrk,justinlin,wjia): Figure out a way to share this code cleanly between
 191 // vanilla WebRTC, Tab Capture, and Pepper Video Capture. Right now there is
 192 // Tab-only stuff and Pepper-only stuff being passed around to all clients,
 193 // which is icky.
 194 struct CONTENT_EXPORT MediaStreamRequest {
 195   MediaStreamRequest(
 196       int render_process_id,
 197       int render_frame_id,
 198       int page_request_id,
 199       const GURL& security_origin,
 200       bool user_gesture,
 201       MediaStreamRequestType request_type,
 202       const std::string& requested_audio_device_id,
 203       const std::string& requested_video_device_id,
 204       MediaStreamType audio_type,
 205       MediaStreamType video_type);
 206
 207   ~MediaStreamRequest();
 208
 209   // This is the render process id for the renderer associated with generating
 210   // frames for a MediaStream. Any indicators associated with a capture will be
 211   // displayed for this renderer.
 212   int render_process_id;
 213
 214   // This is the render frame id for the renderer associated with generating
 215   // frames for a MediaStream. Any indicators associated with a capture will be
 216   // displayed for this renderer.
 217   int render_frame_id;
 218
 219   // The unique id combined with render_process_id and render_frame_id for
 220   // identifying this request. This is used for cancelling request.
 221   int page_request_id;
 222
 223   // Used by tab capture.
 224   std::string tab_capture_device_id;
 225
 226   // The WebKit security origin for the current request (e.g. "html5rocks.com").
 227   GURL security_origin;
 228
 229   // Set to true if the call was made in the context of a user gesture.
 230   bool user_gesture;
 231
 232   // Stores the type of request that was made to the media controller. Right now
 233   // this is only used to distinguish between WebRTC and Pepper requests, as the
 234   // latter should not be subject to user approval but only to policy check.
 235   // Pepper requests are signified by the |MEDIA_OPEN_DEVICE| value.
 236   MediaStreamRequestType request_type;
 237
 238   // Stores the requested raw device id for physical audio or video devices.
 239   std::string requested_audio_device_id;
 240   std::string requested_video_device_id;
 241
 242   // Flag to indicate if the request contains audio.
 243   MediaStreamType audio_type;
 244
 245   // Flag to indicate if the request contains video.
 246   MediaStreamType video_type;
 247 };
 248
 249 // Interface used by the content layer to notify chrome about changes in the
 250 // state of a media stream. Instances of this class are passed to content layer
 251 // when MediaStream access is approved using MediaResponseCallback.
 252 class MediaStreamUI {
 253  public:
 254   virtual ~MediaStreamUI() {}
 255
 256   // Called when MediaStream capturing is started. Chrome layer can call |stop|
 257   // to stop the stream. Returns the platform-dependent window ID for the UI, or
 258   // 0 if not applicable.
 259   virtual gfx::NativeViewId OnStarted(const base::Closure& stop) = 0;
 260 };
 261
 262 // Callback used return results of media access requests.
 263 typedef base::Callback<void(
 264     const MediaStreamDevices& devices,
 265     content::MediaStreamRequestResult result,
 266     scoped_ptr<MediaStreamUI> ui)> MediaResponseCallback;
 267
 268 }  // namespace content
 269
 270 #endif  // CONTENT_PUBLIC_COMMON_MEDIA_STREAM_REQUEST_H_