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 239