ISpMMSysAudio::Read (Windows CE 5.0)

Send Feedback

This method reads the data from the audio device. The audio device should not be directly manipulated when performing speech recognition (see ISpRecognizer).

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 Values

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

OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.

See Also

ISpMMSysAudio | SAPI Interfaces

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.