MICGetState

Syntax

#include <cafe/mic.h>

int MICGetState(mic_handle_t h_mic, mic_state_t state, unsigned int* p_value);

Parameters

h_mic Handle returned from MICInit.
state An enumerated type specifying which value to retrieve.
p_value A pointer to the unsigned integer variable that will receive the requested state value.

Return Values

A value of MIC_ERROR_NONE (zero) indicates success and any other value indicates the type of error that was encountered.

MIC_ERROR_INV_ARG is returned if an invalid handle is passed in. MIC_ERROR_NOT_INIT is returned when the function is called before MICInit or after MICClose. MIC_ERROR_NOT_SUP is returned when getting the quantity specified in state is not supported.

Description

This function is used to query microphone specific properties or current values. For example, this function is used to retrieve the current gain, gain range and resolution.

NOTE:
This function works only when the device is open (for example, following MICOpen) and when audio streaming is in progress. When that is not the case, an error is returned. An application can retry an operation any number of times if an error was returned and the error was due to the streaming state of the microphone data pipeline.

A typical use scenario is setting the gain value of the DRC's microphone. That process consists of the following steps:

NOTE:
The design of the DRC requires that the currently programmed microphone gain value must be read before programming a new value. That retrieved gain value must be compared to the range of valid gain values. It is permissible for this value to be out of range. Such a value is used to indicate a "not ready" state of the device. In that event a new microphone gain value cannot be programmed and the sequence of reading the current gain and programming a new gain value retried. A "device not ready" condition is on the order of hundreds of milliseconds and is associated with plugging or unplugging an external microphone into the DRC.
NOTE:
Opening the data pipeline and the device being ready to return state values are not strictly synchronized. If you want to retrieve or program state values immediately after opening the device, it is recommended that you place logic in a loop that retries the sequence of necessary operations until they succeed or the number of retries is exhausted.

MICGetState is a synchronous call and, depending on the quantity of data to get, will take from a few milliseconds to over one hundred milliseconds to execute, although much of the time is spent waiting on synchronization objects. This function is not meant to be called from timing sensitive threads.

Do Not Call From

Background Do not call this function from the background.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

See Also

mic_handle_t
mic_state_t
MICInit
MICSetState
Error Codes

Revision History

2013/05/08 Automated cleanup pass.
2012/08/03 Cleanup Pass.
2012/06/08 Update to match SDK 2.06.
2011/12/22 Initial version.


CONFIDENTIAL