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