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