src/ppapi/c/dev/ppb_audio_input_dev.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
   6 /* From dev/ppb_audio_input_dev.idl modified Fri May 10 16:06:35 2013. */
   7
   8 #ifndef PPAPI_C_DEV_PPB_AUDIO_INPUT_DEV_H_
   9 #define PPAPI_C_DEV_PPB_AUDIO_INPUT_DEV_H_
  10
  11 #include "ppapi/c/dev/ppb_device_ref_dev.h"
  12 #include "ppapi/c/pp_array_output.h"
  13 #include "ppapi/c/pp_bool.h"
  14 #include "ppapi/c/pp_completion_callback.h"
  15 #include "ppapi/c/pp_instance.h"
  16 #include "ppapi/c/pp_macros.h"
  17 #include "ppapi/c/pp_resource.h"
  18 #include "ppapi/c/pp_stdint.h"
  19 #include "ppapi/c/pp_time.h"
  20
  21 #define PPB_AUDIO_INPUT_DEV_INTERFACE_0_2 "PPB_AudioInput(Dev);0.2"
  22 #define PPB_AUDIO_INPUT_DEV_INTERFACE_0_3 "PPB_AudioInput(Dev);0.3"
  23 #define PPB_AUDIO_INPUT_DEV_INTERFACE_0_4 "PPB_AudioInput(Dev);0.4"
  24 #define PPB_AUDIO_INPUT_DEV_INTERFACE PPB_AUDIO_INPUT_DEV_INTERFACE_0_4
  25
  26 /**
  27  * @file
  28  * This file defines the <code>PPB_AudioInput_Dev</code> interface, which
  29  * provides realtime audio input capture.
  30  */
  31
  32
  33 /**
  34  * @addtogroup Typedefs
  35  * @{
  36  */
  37 /**
  38  * <code>PPB_AudioInput_Callback</code> defines the type of an audio callback
  39  * function used to provide the audio buffer with data. This callback will be
  40  * called on a separate thread from the creation thread.
  41  *
  42  * @param[in] sample_buffer A buffer providing audio input data.
  43  * @param[in] buffer_size_in_bytes The size of the buffer in bytes.
  44  * @param[in] latency The time that has elapsed since the data was recorded.
  45  * @param[inout] user_data An opaque pointer that was passed into
  46  * <code>PPB_AudioInput_Dev.Open()</code>.
  47  */
  48 typedef void (*PPB_AudioInput_Callback)(const void* sample_buffer,
  49                                         uint32_t buffer_size_in_bytes,
  50                                         PP_TimeDelta latency,
  51                                         void* user_data);
  52
  53 typedef void (*PPB_AudioInput_Callback_0_2)(const void* sample_buffer,
  54                                             uint32_t buffer_size_in_bytes,
  55                                             void* user_data);
  56 /**
  57  * @}
  58  */
  59
  60 /**
  61  * @addtogroup Interfaces
  62  * @{
  63  */
  64 /**
  65  * The <code>PPB_AudioInput_Dev</code> interface contains pointers to several
  66  * functions for handling audio input resources.
  67  *
  68  * TODO(brettw) before moving out of dev, we need to resolve the issue of
  69  * the mismatch between the current audio config interface and this one.
  70  *
  71  * In particular, the params for input assume stereo, but this class takes
  72  * everything as mono. We either need to not use an audio config resource, or
  73  * add mono support.
  74  *
  75  * In addition, RecommendSampleFrameCount is completely wrong for audio input.
  76  * RecommendSampleFrameCount returns the frame count for the current
  77  * low-latency output device, which is likely inappropriate for a random input
  78  * device. We may want to move the "recommend" functions to the input or output
  79  * classes rather than the config.
  80  */
  81 struct PPB_AudioInput_Dev_0_4 {
  82   /**
  83    * Creates an audio input resource.
  84    *
  85    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
  86    * a module.
  87    *
  88    * @return A <code>PP_Resource</code> corresponding to an audio input resource
  89    * if successful, 0 if failed.
  90    */
  91   PP_Resource (*Create)(PP_Instance instance);
  92   /**
  93    * Determines if the given resource is an audio input resource.
  94    *
  95    * @param[in] resource A <code>PP_Resource</code> containing a resource.
  96    *
  97    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
  98    * resource is an audio input resource, otherwise <code>PP_FALSE</code>.
  99    */
 100   PP_Bool (*IsAudioInput)(PP_Resource resource);
 101   /**
 102    * Enumerates audio input devices.
 103    *
 104    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 105    * input resource.
 106    * @param[in] output An output array which will receive
 107    * <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the
 108    * ref count of those resources has already been increased by 1 for the
 109    * caller.
 110    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
 111    * completion.
 112    *
 113    * @return An error code from <code>pp_errors.h</code>.
 114    */
 115   int32_t (*EnumerateDevices)(PP_Resource audio_input,
 116                               struct PP_ArrayOutput output,
 117                               struct PP_CompletionCallback callback);
 118   /**
 119    * Requests device change notifications.
 120    *
 121    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 122    * input resource.
 123    * @param[in] callback The callback to receive notifications. If not NULL, it
 124    * will be called once for the currently available devices, and then every
 125    * time the list of available devices changes. All calls will happen on the
 126    * same thread as the one on which MonitorDeviceChange() is called. It will
 127    * receive notifications until <code>audio_input</code> is destroyed or
 128    * <code>MonitorDeviceChange()</code> is called to set a new callback for
 129    * <code>audio_input</code>. You can pass NULL to cancel sending
 130    * notifications.
 131    * @param[inout] user_data An opaque pointer that will be passed to
 132    * <code>callback</code>.
 133    *
 134    * @return An error code from <code>pp_errors.h</code>.
 135    */
 136   int32_t (*MonitorDeviceChange)(PP_Resource audio_input,
 137                                  PP_MonitorDeviceChangeCallback callback,
 138                                  void* user_data);
 139   /**
 140    * Opens an audio input device. No sound will be captured until
 141    * StartCapture() is called.
 142    *
 143    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 144    * input resource.
 145    * @param[in] device_ref Identifies an audio input device. It could be one of
 146    * the resource in the array returned by EnumerateDevices(), or 0 which means
 147    * the default device.
 148    * @param[in] config A <code>PPB_AudioConfig</code> audio configuration
 149    * resource.
 150    * @param[in] audio_input_callback A <code>PPB_AudioInput_Callback</code>
 151    * function that will be called when data is available.
 152    * @param[inout] user_data An opaque pointer that will be passed into
 153    * <code>audio_input_callback</code>.
 154    * @param[in] callback A <code>PP_CompletionCallback</code> to run when this
 155    * open operation is completed.
 156    *
 157    * @return An error code from <code>pp_errors.h</code>.
 158    */
 159   int32_t (*Open)(PP_Resource audio_input,
 160                   PP_Resource device_ref,
 161                   PP_Resource config,
 162                   PPB_AudioInput_Callback audio_input_callback,
 163                   void* user_data,
 164                   struct PP_CompletionCallback callback);
 165   /**
 166    * Returns an audio config resource for the given audio input resource.
 167    *
 168    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 169    * input resource.
 170    *
 171    * @return A <code>PP_Resource</code> containing the audio config resource if
 172    * successful.
 173    */
 174   PP_Resource (*GetCurrentConfig)(PP_Resource audio_input);
 175   /**
 176    * Starts the capture of the audio input resource and begins periodically
 177    * calling the callback.
 178    *
 179    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 180    * input resource.
 181    *
 182    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 183    * successful, otherwise <code>PP_FALSE</code>.
 184    * Also returns <code>PP_TRUE</code> (and is a no-op) if called while capture
 185    * is already started.
 186    */
 187   PP_Bool (*StartCapture)(PP_Resource audio_input);
 188   /**
 189    * Stops the capture of the audio input resource.
 190    *
 191    * @param[in] audio_input A PP_Resource containing the audio input resource.
 192    *
 193    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 194    * successful, otherwise <code>PP_FALSE</code>.
 195    * Also returns <code>PP_TRUE</code> (and is a no-op) if called while capture
 196    * is already stopped. If a buffer is being captured, StopCapture will block
 197    * until the call completes.
 198    */
 199   PP_Bool (*StopCapture)(PP_Resource audio_input);
 200   /**
 201    * Closes the audio input device, and stops capturing if necessary. It is
 202    * not valid to call Open() again after a call to this method.
 203    * If an audio input resource is destroyed while a device is still open, then
 204    * it will be implicitly closed, so you are not required to call this method.
 205    *
 206    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 207    * input resource.
 208    */
 209   void (*Close)(PP_Resource audio_input);
 210 };
 211
 212 typedef struct PPB_AudioInput_Dev_0_4 PPB_AudioInput_Dev;
 213
 214 struct PPB_AudioInput_Dev_0_2 {
 215   PP_Resource (*Create)(PP_Instance instance);
 216   PP_Bool (*IsAudioInput)(PP_Resource resource);
 217   int32_t (*EnumerateDevices)(PP_Resource audio_input,
 218                               PP_Resource* devices,
 219                               struct PP_CompletionCallback callback);
 220   int32_t (*Open)(PP_Resource audio_input,
 221                   PP_Resource device_ref,
 222                   PP_Resource config,
 223                   PPB_AudioInput_Callback_0_2 audio_input_callback,
 224                   void* user_data,
 225                   struct PP_CompletionCallback callback);
 226   PP_Resource (*GetCurrentConfig)(PP_Resource audio_input);
 227   PP_Bool (*StartCapture)(PP_Resource audio_input);
 228   PP_Bool (*StopCapture)(PP_Resource audio_input);
 229   void (*Close)(PP_Resource audio_input);
 230 };
 231
 232 struct PPB_AudioInput_Dev_0_3 {
 233   PP_Resource (*Create)(PP_Instance instance);
 234   PP_Bool (*IsAudioInput)(PP_Resource resource);
 235   int32_t (*EnumerateDevices)(PP_Resource audio_input,
 236                               struct PP_ArrayOutput output,
 237                               struct PP_CompletionCallback callback);
 238   int32_t (*MonitorDeviceChange)(PP_Resource audio_input,
 239                                  PP_MonitorDeviceChangeCallback callback,
 240                                  void* user_data);
 241   int32_t (*Open)(PP_Resource audio_input,
 242                   PP_Resource device_ref,
 243                   PP_Resource config,
 244                   PPB_AudioInput_Callback_0_2 audio_input_callback,
 245                   void* user_data,
 246                   struct PP_CompletionCallback callback);
 247   PP_Resource (*GetCurrentConfig)(PP_Resource audio_input);
 248   PP_Bool (*StartCapture)(PP_Resource audio_input);
 249   PP_Bool (*StopCapture)(PP_Resource audio_input);
 250   void (*Close)(PP_Resource audio_input);
 251 };
 252 /**
 253  * @}
 254  */
 255
 256 #endif  /* PPAPI_C_DEV_PPB_AUDIO_INPUT_DEV_H_ */
 257