ppapi/api/dev/ppb_audio_input_dev.idl

   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 /**
   7  * This file defines the <code>PPB_AudioInput_Dev</code> interface, which
   8  * provides realtime audio input capture.
   9  */
  10
  11 label Chrome {
  12   M19 = 0.2,
  13   M25 = 0.3
  14 };
  15
  16 /**
  17  * <code>PPB_AudioInput_Callback</code> defines the type of an audio callback
  18  * function used to provide the audio buffer with data. This callback will be
  19  * called on a separate thread from the creation thread.
  20  */
  21 typedef void PPB_AudioInput_Callback([in] mem_t sample_buffer,
  22                                      [in] uint32_t buffer_size_in_bytes,
  23                                      [inout] mem_t user_data);
  24
  25 /**
  26  * The <code>PPB_AudioInput_Dev</code> interface contains pointers to several
  27  * functions for handling audio input resources.
  28  *
  29  * TODO(brettw) before moving out of dev, we need to resolve the issue of
  30  * the mismatch between the current audio config interface and this one.
  31  *
  32  * In particular, the params for input assume stereo, but this class takes
  33  * everything as mono. We either need to not use an audio config resource, or
  34  * add mono support.
  35  *
  36  * In addition, RecommendSampleFrameCount is completely wrong for audio input.
  37  * RecommendSampleFrameCount returns the frame count for the current
  38  * low-latency output device, which is likely inappropriate for a random input
  39  * device. We may want to move the "recommend" functions to the input or output
  40  * classes rather than the config.
  41  */
  42 [macro="PPB_AUDIO_INPUT_DEV_INTERFACE"]
  43 interface PPB_AudioInput_Dev {
  44   /**
  45    * Creates an audio input resource.
  46    *
  47    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
  48    * a module.
  49    *
  50    * @return A <code>PP_Resource</code> corresponding to an audio input resource
  51    * if successful, 0 if failed.
  52    */
  53   PP_Resource Create(
  54       [in] PP_Instance instance);
  55
  56   /**
  57    * Determines if the given resource is an audio input resource.
  58    *
  59    * @param[in] resource A <code>PP_Resource</code> containing a resource.
  60    *
  61    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
  62    * resource is an audio input resource, otherwise <code>PP_FALSE</code>.
  63    */
  64   PP_Bool IsAudioInput(
  65       [in] PP_Resource resource);
  66
  67   /**
  68    * Enumerates audio input devices.
  69    *
  70    * Please note that:
  71    * - this method ignores the previous value pointed to by <code>devices</code>
  72    *   (won't release reference even if it is not 0);
  73    * - <code>devices</code> must be valid until <code>callback</code> is called,
  74    *   if the method returns <code>PP_OK_COMPLETIONPENDING</code>;
  75    * - the ref count of the returned <code>devices</code> has already been
  76    *   increased by 1 for the caller.
  77    *
  78    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
  79    * input resource.
  80    * @param[out] devices Once the operation is completed successfully,
  81    * <code>devices</code> will be set to a <code>PPB_ResourceArray_Dev</code>
  82    * resource, which holds a list of <code>PPB_DeviceRef_Dev</code> resources.
  83    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
  84    * completion.
  85    *
  86    * @return An error code from <code>pp_errors.h</code>.
  87    */
  88   [deprecate=0.3]
  89   int32_t EnumerateDevices(
  90       [in] PP_Resource audio_input,
  91       [out] PP_Resource devices,
  92       [in] PP_CompletionCallback callback);
  93
  94   /**
  95    * Enumerates audio input devices.
  96    *
  97    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
  98    * input resource.
  99    * @param[in] output An output array which will receive
 100    * <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the
 101    * ref count of those resources has already been increased by 1 for the
 102    * caller.
 103    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
 104    * completion.
 105    *
 106    * @return An error code from <code>pp_errors.h</code>.
 107    */
 108   [version=0.3]
 109   int32_t EnumerateDevices(
 110       [in] PP_Resource audio_input,
 111       [in] PP_ArrayOutput output,
 112       [in] PP_CompletionCallback callback);
 113
 114   /**
 115    * Requests device change notifications.
 116    *
 117    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 118    * input resource.
 119    * @param[in] callback The callback to receive notifications. If not NULL, it
 120    * will be called once for the currently available devices, and then every
 121    * time the list of available devices changes. All calls will happen on the
 122    * same thread as the one on which MonitorDeviceChange() is called. It will
 123    * receive notifications until <code>audio_input</code> is destroyed or
 124    * <code>MonitorDeviceChange()</code> is called to set a new callback for
 125    * <code>audio_input</code>. You can pass NULL to cancel sending
 126    * notifications.
 127    * @param[inout] user_data An opaque pointer that will be passed to
 128    * <code>callback</code>.
 129    *
 130    * @return An error code from <code>pp_errors.h</code>.
 131    */
 132   [version=0.3]
 133   int32_t MonitorDeviceChange(
 134       [in] PP_Resource audio_input,
 135       [in] PP_MonitorDeviceChangeCallback callback,
 136       [inout] mem_t user_data);
 137
 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(
 159       [in] PP_Resource audio_input,
 160       [in] PP_Resource device_ref,
 161       [in] PP_Resource config,
 162       [in] PPB_AudioInput_Callback audio_input_callback,
 163       [inout] mem_t user_data,
 164       [in] PP_CompletionCallback callback);
 165
 166   /**
 167    * Returns an audio config resource for the given audio input resource.
 168    *
 169    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 170    * input resource.
 171    *
 172    * @return A <code>PP_Resource</code> containing the audio config resource if
 173    * successful.
 174    */
 175   PP_Resource GetCurrentConfig(
 176       [in] PP_Resource audio_input);
 177
 178   /**
 179    * Starts the capture of the audio input resource and begins periodically
 180    * calling the callback.
 181    *
 182    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 183    * input resource.
 184    *
 185    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 186    * successful, otherwise <code>PP_FALSE</code>.
 187    * Also returns <code>PP_TRUE</code> (and is a no-op) if called while capture
 188    * is already started.
 189    */
 190   PP_Bool StartCapture(
 191       [in] PP_Resource audio_input);
 192
 193   /**
 194    * Stops the capture of the audio input resource.
 195    *
 196    * @param[in] audio_input A PP_Resource containing the audio input resource.
 197    *
 198    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 199    * successful, otherwise <code>PP_FALSE</code>.
 200    * Also returns <code>PP_TRUE</code> (and is a no-op) if called while capture
 201    * is already stopped. If a buffer is being captured, StopCapture will block
 202    * until the call completes.
 203    */
 204   PP_Bool StopCapture(
 205       [in] PP_Resource audio_input);
 206
 207   /**
 208    * Closes the audio input device, and stops capturing if necessary. It is
 209    * not valid to call Open() again after a call to this method.
 210    * If an audio input resource is destroyed while a device is still open, then
 211    * it will be implicitly closed, so you are not required to call this method.
 212    *
 213    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 214    * input resource.
 215    */
 216   void Close(
 217       [in] PP_Resource audio_input);
 218 };