blob: fe2823f1af0083387d0493e73332f2773e2e3259 [file] [log] [blame]
/* 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,
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.
*/
[macro="PPB_AUDIO_INPUT_DEV_INTERFACE"]
interface PPB_AudioInput_Dev {
[deprecate=0.2]
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);
/**
* Determines if the given resource is an audio input 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 input resource, otherwise <code>PP_FALSE</code>.
*/
PP_Bool IsAudioInput(
[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);
/**
* Returns an audio config resource for the given audio input 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);
/**
* Starts the capture of the audio input resource and begins periodically
* calling the callback.
*
* @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 is a no-op) if called while capture
* is already started.
*/
PP_Bool StartCapture(
[in] PP_Resource audio_input);
/**
* Stops the capture of the audio input resource.
*
* @param[in] audio_input A PP_Resource containing the 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 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);
};