ISpSREngineSite::Read (SAPI 5.4)

Microsoft Speech API 5.4

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. The size of the buffer must be at least cb bytes.
• 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

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.