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