ISpSREngineSite::Read
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This method reads audio data from the audio input stream. The SR engine calls it while the engine is processing an ISpSREngine::RecognizeStream call. It can be called on any thread.
In the call to this method, the engine requests a certain amount of data to read and supplies a buffer of the appropriate size. SAPI reads the requested amount of data from the audio input. If the amount of data that is requested is not available immediately, SAPI blocks the call until the requested amount is available.
If this method returns with a failure code or if the amount read is less than the amount requested, the stream has ended. The ISpSREngine::RecognizeStream method should return after it has finished processing all data. If ISpSREngineSite::Read returns a failure code, the engine should not return it as the return value of the ISpSREngine::RecognizeStream method. This failure code can occur for typical conditions indicating that the audio has finished.
Syntax
HRESULT Read(
void* pv,
ULONG cb,
ULONG* pcbRead
);
Parameters
- pv
[in] Pointer to the buffer to receive audio input stream data.
- cb
[in] Number of bytes of data to read from the audio input stream.
- pcbRead
[out] Pointer to the actual number of bytes read from the audio input stream.
Remarks
When the SR engine calls this method, SAPI calls ISpAudio::GetBufferInfo and passes the return code back to the SR engine. If an error code is returned and the error is recoverable, SAPI automatically detects that an audio error occurred and attempts to reactivate the audio device. The SR engine will then receive a new call at 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 ISpSREngineSite::Read as often as it can to avoid an audio buffer overflow. For an example, see ISpMMSysAudio::Read.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
SPERR_AUDIO_BUFFER_OVERFLOW |
Internal SAPI audio buffer has filled, and the device has been closed. See Remarks section. |
SPERR_AUDIO_BUFFER_UNDERFLOW |
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 and pv parameters is invalid or bad. |
FAILED(hr) |
Other appropriate error message. |
Requirements
| Header | sapiddk.h, sapiddk.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |