ISpMMSysAudio::Read (Windows Embedded CE 6.0)
1/6/2010
This method reads the data from the audio device. The audio device should not be directly manipulated when performing speech recognition (see ISpRecognizer).
Syntax
HRESULT Read(
void* pv,
ULONG cb,
ULONG* pcbRead
);
Parameters
- pv
[in] Pointer to the buffer into which the stream data is read. If an error occurs, this value is NULL.
- cb
[in] Number of bytes of data to attempt to read from the audio device.
- pcbRead
[out] Pointer to actual number of bytes read from the stream object. If set to NULL, no byte value is retrieved.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
SPERR_AUDIO_BUFFER_OVERFLOW |
SAPI's internal audio buffer has filled, and the device has been closed. |
SPERR_AUDIO_BUFFER_UNDERFLOW |
The multimedia object has not received audio data from the device quickly enough, and the device has been closed. |
SPERR_AUDIO_STOPPED |
Multimedia device state has been set to stopped. |
E_OUTOFMEMORY |
Exceeded available memory |
E_POINTER |
At least one of pcbRead or pv are invalid or bad. |
STG_E_ACCESSDENIED |
Multimedia device is read-only and no bytes will be read. Error will occur when reading from an output device. |
FAILED(hr) |
Appropriate error message. |
Remarks
SAPI automatically stores data in a buffer before it is read from the device. Buffering the audio data ensures that applications and SAPI-compliant speech recognition engines will not lose real-time audio data.
An errant application or speech recognition engine that does not call Read often enough could frequently fill the audio buffer. To ensure that large amounts of system memory are not filled, SAPI limits the buffer size to 30 times the average bytes per second (WAVEFORMATEX->nAvgBytesPerSec) - approximately 30 seconds. If the audio buffer is filled, then SAPI will automatically set the device state to SPAS_CLOSED (see SPAUDIOSTATE) and return a buffer overflow error (for example, SPERR_AUDIO_BUFFER_OVERFLOW) when ISpMMSysAudio::Read is called.
An errant multimedia device (and, or driver) that does not return audio data quickly enough could greatly reduce the speed of a speech application or SR engine. To prevent the degradation of application or SR engine performance, SAPI requires that the multimedia device return data at least once every five seconds. If the audio is not returned before five seconds, SAPI will automatically set the device state to SPAS_CLOSED (see SPAUDIOSTATE) and return a buffer underflow error (for example, SPERR_AUDIO_BUFFER_UNDERFLOW) when ISpMMSysAudio::Read is called.
Applications should manually reopen the audio device (see ISpAudio::SetState) to prevent losing input data that could impact the user.
For Speech Recognition engines, SAPI will automatically attempt to restart the multimedia device after the SR Engine exits the ISpSREngine::RecognizeStream call.
Requirements
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |