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