Support audio output device enumeration and selection in PPAPI

ppapi/api/dev/ppb_audio_output_dev.idl

+/* Copyright (c) 2017 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_AudioOutput_dev</code> interface, which
+ * provides realtime stereo audio streaming capabilities.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  M59 = 0.1
+};
+
+/**
+ * <code>PPB_AudioOutput_Callback</code> defines the type of an audio callback
+ * function used to fill the audio buffer with data. Please see the
+ * Create() function in the <code>PPB_AudioOutput</code> interface for
+ * more details on this callback.
+ *
+ * @param[out] sample_buffer A buffer to fill with audio data.
+ * @param[in] buffer_size_in_bytes The size of the buffer in bytes.
+ * @param[in] latency How long before the audio data is to be presented.
+ * @param[inout] user_data An opaque pointer that was passed into
+ * <code>PPB_AudioOutput.Create()</code>.
+ */
+typedef void PPB_AudioOutput_Callback([out] mem_t sample_buffer,
+                                      [in] uint32_t buffer_size_in_bytes,
+                                      [in] PP_TimeDelta latency,
+                                      [inout] mem_t user_data);
+
+/**
+ * The <code>PPB_AudioOutput</code> interface contains pointers to several
+ * functions for handling audio resources.
+ * Please see descriptions for each <code>PPB_AudioOutput</code> and
+ * <code>PPB_AudioConfig</code> function for more details. A C example using
+ * <code>PPB_AudioOutput</code> and <code>PPB_AudioConfig</code> follows.
+ *
+ * <strong>Example: </strong>
+ * 
+ * @code
+ * void audio_output_callback(void* sample_buffer,
+ *                            uint32_t buffer_size_in_bytes,
+ *                            PP_TimeDelta latency,
+ *                            void* user_data) {
+ *   ... quickly fill in the buffer with samples and return to caller ...
+ *  }
+ *
+ * ...Assume the application has cached the audio configuration interface in
+ * audio_config_interface and the audio interface in
+ * audio_output_interface...
+ *
+ * uint32_t count = audio_config_interface->RecommendSampleFrameCount(
+ *     PP_AUDIOSAMPLERATE_44100, 4096);
+ * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit(
+ *     pp_instance, PP_AUDIOSAMPLERATE_44100, count);
+ * PP_Resource pp_audio_output = audio_interface->Create(pp_instance,
+ *     pp_audio_config, audio_callback, NULL);
+ * audio_interface->EnumerateDevices(pp_audio_output, output_device_list,
+ *     callback);
+ * audio_interface->Open(pp_audio_output, device_ref, pp_audio_config,
+ *     audio_output_callback, user_data, callback);
+ * audio_output_interface->StartPlayback(pp_audio_output);
+ *
+ * ...audio_output_callback() will now be periodically invoked on a separate
+ * thread...
+ * @endcode
+ */
+
+[macro="PPB_AUDIO_OUTPUT_DEV_INTERFACE"]
+interface PPB_AudioOutput_Dev {
+  /**
+   * Creates an audio output 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 output resource
+   * if successful, 0 if failed.
+   */
+  PP_Resource Create(
+      [in] PP_Instance instance);
+
+  /**
+   * Determines if the given resource is an audio output resource.
+   *
+   * @param[in] resource A <code>PP_Resource</code> containing a resource.
+   *
+   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
+   * resource is an audio output resource, otherwise <code>PP_FALSE</code>.
+   */
+  PP_Bool IsAudioOutput(
+      [in] PP_Resource resource);
+
+  /**
+   * Enumerates audio output devices.
+   *
+   * @param[in] audio_output A <code>PP_Resource</code> corresponding to an audio
+   * output resource.
+   * @param[in] output An output array which will receive
+   * <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the
+   * ref count of those resources has already been increased by 1 for the
+   * caller.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
+   * completion.
+   *
+   * @return An error code from <code>pp_errors.h</code>.
+   */
+  int32_t EnumerateDevices(
+      [in] PP_Resource audio_output,
+      [in] PP_ArrayOutput output,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Requests device change notifications.
+   *
+   * @param[in] audio_output A <code>PP_Resource</code> corresponding to an audio
+   * output resource.
+   * @param[in] callback The callback to receive notifications. If not NULL, it
+   * will be called once for the currently available devices, and then every
+   * time the list of available devices changes. All calls will happen on the
+   * same thread as the one on which MonitorDeviceChange() is called. It will
+   * receive notifications until <code>audio_output</code> is destroyed or
+   * <code>MonitorDeviceChange()</code> is called to set a new callback for
+   * <code>audio_output</code>. You can pass NULL to cancel sending
+   * notifications.
+   * @param[inout] user_data An opaque pointer that will be passed to
+   * <code>callback</code>.
+   *
+   * @return An error code from <code>pp_errors.h</code>.
+   */
+  int32_t MonitorDeviceChange(
+      [in] PP_Resource audio_output,
+      [in] PP_MonitorDeviceChangeCallback callback,
+      [inout] mem_t user_data);
+
+  /**
+   * Open() opens an audio output device. No sound will be heard until
+   * StartPlayback() is called. The callback is called with the buffer address
+   * and given user data whenever the buffer needs to be filled. From within the
+   * callback, you should not call <code>PPB_AudioOutput</code> functions. The
+   * callback will be called on a different thread than the one which created
+   * the interface. For performance-critical applications (i.e. low-latency
+   * audio), the callback should avoid blocking or calling functions that can
+   * obtain locks, such as malloc. The layout and the size of the buffer passed
+   * to the audio callback will be determined by the device configuration and is
+   * specified in the <code>AudioConfig</code> documentation.
+   *
+   * @param[in] audio_output A <code>PP_Resource</code> corresponding to an audio
+   * output resource.
+   * @param[in] device_ref Identifies an audio output 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_output_callback A <code>PPB_AudioOutput_Callback</code>
+   * function that will be called when audio buffer needs to be filled.
+   * @param[inout] user_data An opaque pointer that will be passed into
+   * <code>audio_output_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>.
+   */
+  int32_t Open(
+      [in] PP_Resource audio_output,
+      [in] PP_Resource device_ref,
+      [in] PP_Resource config,
+      [in] PPB_AudioOutput_Callback audio_output_callback,
+      [inout] mem_t user_data,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * GetCurrrentConfig() returns an audio config resource for the given audio
+   * output resource.
+   *
+   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
+   * output resource.
+   *
+   * @return A <code>PP_Resource</code> containing the audio config resource if
+   * successful.
+   */
+  PP_Resource GetCurrentConfig(
+      [in] PP_Resource audio_output);
+
+  /**
+   * StartPlayback() starts the playback of the audio output resource and begins
+   * periodically calling the callback.
+   *
+   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
+   * output 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 playback is already
+   * in progress.
+   */
+  PP_Bool StartPlayback(
+      [in] PP_Resource audio_output);
+
+  /**
+   * StopPlayback() stops the playback of the audio resource.
+   *
+   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
+   * output 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 is a no-op) if called while playback is already
+   * stopped. If a callback is in progress, StopPlayback() will block until the
+   * callback completes.
+   */
+  PP_Bool StopPlayback(
+      [in] PP_Resource audio_output);
+
+  /**
+   * Close() closes the audio output device, and stops playback if necessary. It is
+   * not valid to call Open() again after a call to this method.
+   * If an audio output 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_output A <code>PP_Resource</code> corresponding to an audio
+   * output resource.
+   */
+  void Close(
+      [in] PP_Resource audio_output);
+};