PPB_AudioInput_Dev: support multiple audio input devices - Part 1.

ppapi/api/dev/ppb_audio_input_dev.idl

 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 /**
  * This file defines the <code>PPB_AudioInput_Dev</code> interface, which
  * provides realtime audio input capture.
  */
 
 label Chrome {
-  M17 = 0.1
+  M17 = 0.1,
+  M19 = 0.2
 };
 
 /**
  * <code>PPB_AudioInput_Callback</code> defines the type of an audio callback
  * function used to provide the audio buffer with data. This callback will be
  * called on a separate thread from the creation thread.
  */
 typedef void PPB_AudioInput_Callback([in] mem_t sample_buffer,
                                      [in] uint32_t buffer_size_in_bytes,
                                      [inout] mem_t user_data);
 
 /**
  * The <code>PPB_AudioInput_Dev</code> interface contains pointers to several
  * functions for handling audio input resources.
  */
-[version=0.1, macro="PPB_AUDIO_INPUT_DEV_INTERFACE"]
+[macro="PPB_AUDIO_INPUT_DEV_INTERFACE"]
 interface PPB_AudioInput_Dev {
-  /**
-   * Create is a pointer to a function that creates an audio input resource.
-   * No sound will be captured until StartCapture() is called.
-   */
+  [version=0.1]
   PP_Resource Create(
       [in] PP_Instance instance,
       [in] PP_Resource config,
       [in] PPB_AudioInput_Callback audio_input_callback,
       [inout] mem_t user_data);
 
   /**
+   * Creates an audio input resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   *
+   * @return A <code>PP_Resource</code> corresponding to an audio input resource
+   * if successful, 0 if failed.
+   */
+  [version=0.2]
+  PP_Resource Create(
+      [in] PP_Instance instance);
+
+  /**
    * IsAudioInput is a pointer to a function that determines if the given
    * resource is an audio input resource.
    *
-   * @param[in] resource A PP_Resource containing a resource.
+   * @param[in] resource A <code>PP_Resource</code> containing a resource.
    *
-   * @return A PP_BOOL containing containing PP_TRUE if the given resource is
-   * an audio input resource, otherwise PP_FALSE.
+   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
+   * resource is an audio input resource, otherwise <code>PP_FALSE</code>.
    */
   PP_Bool IsAudioInput(
-      [in] PP_Resource audio_input);
+      [in] PP_Resource resource);
+
+  /**
+   * Enumerates audio input devices.
+   *
+   * Please note that:
+   * - this method ignores the previous value pointed to by <code>devices</code>
+   *   (won't release reference even if it is not 0);
+   * - <code>devices</code> must be valid until <code>callback</code> is called,
+   *   if the method returns <code>PP_OK_COMPLETIONPENDING</code>;
+   * - the ref count of the returned <code>devices</code> has already been
+   *   increased by 1 for the caller.
+   *
+   * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
+   * input resource.
+   * @param[out] devices Once the operation is completed successfully,
+   * <code>devices</code> will be set to a <code>PPB_ResourceArray_Dev</code>
+   * resource, which holds a list of <code>PPB_DeviceRef_Dev</code> resources.
+   * @param[in] callback  A <code>PP_CompletionCallback</code> to run on
+   * completion.
+   *
+   * @return An error code from <code>pp_errors.h</code>.
+   */
+  [version=0.2]
+  int32_t EnumerateDevices(
+      [in] PP_Resource audio_input,
+      [out] PP_Resource devices,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Opens an audio input device. No sound will be captured until
+   * StartCapture() is called.
+   *
+   * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
+   * input resource.
+   * @param[in] device_ref Identifies an audio input device. It could be one of
+   * the resource in the array returned by EnumerateDevices(), or 0 which means
+   * the default device.
+   * @param[in] config A <code>PPB_AudioConfig</code> audio configuration
+   * resource.
+   * @param[in] audio_input_callback A <code>PPB_AudioInput_Callback</code>
+   * function that will be called when data is available.
+   * @param[inout] user_data An opaque pointer that will be passed into
+   * <code>audio_input_callback</code>.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to run when this
+   * open operation is completed.
+   *
+   * @return An error code from <code>pp_errors.h</code>.
+   */
+  [version=0.2]
+  int32_t Open(
+      [in] PP_Resource audio_input,
+      [in] PP_Resource device_ref,
+      [in] PP_Resource config,
+      [in] PPB_AudioInput_Callback audio_input_callback,
+      [inout] mem_t user_data,
+      [in] PP_CompletionCallback callback);
 
   /**
    * GetCurrrentConfig() returns an audio config resource for the given audio
-   * resource.
+   * input resource.
    *
-   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
-   * resource.
+   * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
+   * input resource.
    *
    * @return A <code>PP_Resource</code> containing the audio config resource if
    * successful.
    */
   PP_Resource GetCurrentConfig(
       [in] PP_Resource audio_input);
 
   /**
    * StartCapture() starts the capture of the audio input resource and begins

[brettw, 2012/03/02 19:13:41]

Can both start & stop note that they return true if the audio capture is already
started/stopped?

[yzshen1, 2012/03/04 08:04:01]

Done.

    * periodically calling the callback.
    *
-   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
+   * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
    * input resource.
    *
    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
-   * successful, otherwise <code>PP_FALSE</code>. Also returns
-   * <code>PP_TRUE</code> (and be a no-op) if called while callback is already
-   * in progress.
+   * successful, otherwise <code>PP_FALSE</code>.
    */
   PP_Bool StartCapture(
       [in] PP_Resource audio_input);
 
   /**

[brettw, 2012/03/02 19:13:41]

Can you remove "pointer to a function" here?

[yzshen1, 2012/03/04 08:04:01]

Done.

    * StopCapture is a pointer to a function that stops the capture of
    * the audio input resource.
    *
-   * @param[in] config A PP_Resource containing the audio input resource.
+   * @param[in] audio_input A PP_Resource containing the audio input resource.
    *
-   * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.
-   * Also returns PP_TRUE (and is a no-op) if called while capture is already
-   * stopped. If a buffer is being captured, StopCapture will block until the
-   * call completes.
+   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
+   * successful, otherwise <code>PP_FALSE</code>.
+   * Also returns <code>PP_TRUE</code> (and is a no-op) if called while capture
+   * is already stopped. If a buffer is being captured, StopCapture will block
+   * until the call completes.
    */
   PP_Bool StopCapture(
       [in] PP_Resource audio_input);
+
+  /**
+   * Closes the audio input device, and stops capturing if necessary. It is
+   * not valid to call Open() again after a call to this method.
+   * If an audio input resource is destroyed while a device is still open, then
+   * it will be implicitly closed, so you are not required to call this method.
+   *
+   * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
+   * input resource.
+   */
+  [version=0.2]
+  void Close(
+      [in] PP_Resource audio_input);
 };
-