Microsoft Speech SDK SAPI 5.1

---

ISpSREngineSite::Read

ISpSREngineSite::Read retrieves a chunk of audio data for the SR engine to convert to text.

HRESULT Read(
   void    *pv,
   ULONG    cb,
   ULONG   *pcbRead
);

Parameters

pv

[in] Pointer to the buffer into which the audio input stream data is read.

cb

[in] Specifies the number of bytes of data to attempt to read from the audio input stream.

pcbRead

[out] Pointer to a ULONG variable that receives the actual number of bytes read from the audio input stream. 

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. See Remarks section.
SPERR_AUDIO_BUFFER_UNDERFLOW	The audio object has not received audio data from the device quickly enough, and the device has been closed. See Remarks section.
SPERR_AUDIO_STOPPED	Audio device state has been set to stop.
SPERR_STREAM_NOT_ACTIVE	Method called when engine is not inside RecognizeStream call.
E_OUTOFMEMORY	Exceeded available memory
E_POINTER	At least one of pcbRead or pv are invalid or bad.
FAILED (hr)	Other appropriate error message.

Remarks

The engine requests a certain amount of data to read and supplies a buffer of this size. SAPI will read this amount of data from the audio input. If the amount of data that is requested is not available immediately, SAPI will block this call until the requested amount is available. 

If this call returns with a failure code or if the amount that was read is less than the amount requested, this indicates that the stream has ended. The engine should return from the RecognizeStream method after it has finished processing all data.

This method can only be called while the SR engine is inside a ISpSREngine::RecognizeStream call, although it can be called on any thread.

When the SR engine calls ISpSREngineSite::Read, SAPI will ultimately call ISpAudio::Read and pass the return code back to the SR engine using ISpSREngineSite::Read. If an error code is returned and the error is recoverable, SAPI will automatically detect that an audio error occurred and attempt to reactivate the audio device. The SR engine will then receive a new call, ISpSREngine::RecognizeStream, that will enable it to continue recognizing with minimal audio data loss.

When using a real-time audio device as input, it is important for an SR engine to call Read as often as it is able to avoid an audio buffer overflow (for example see ISpMMSysAudio::Read).

In all cases, if the Read call returns a failure code, the engine should not return this as the return value of the RecognizeStream method. This failure code can occur for normal conditions indicating the audio has finished.