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 */
47typedef void (*PPB_AudioInput_Callback)(const void* sample_buffer,
48                                        uint32_t buffer_size_in_bytes,
49                                        PP_TimeDelta latency,
50                                        void* user_data);
51
52typedef 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 */
80struct 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
211typedef struct PPB_AudioInput_Dev_0_4 PPB_AudioInput_Dev;
212
213struct 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