ISpRecoContext::Pause
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 pauses the recognition process to allow SR engine synchronization. The SR engine pauses at its synchronization point to allow grammars and rule states to be changed freely. The context remains paused until the ISpRecoContext::Resume method is called. The caller must call Resume once for every call that is made to Pause.
Syntax
HRESULT Pause(
DWORD dwFlags
);
Parameters
- dwFlags
[in] Reserved. Must be zero.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
E_INVALIDARG |
dwFlags is not set to zero. |
Remarks (when using ISpMMSysAudio as audio input)
Pausing the SR engine will stop recognition, but input audio will continue to be collected and stored by SAPI in an audio buffer. After the application is done with the state change, it should call ISpRecoContext::Resume. SAPI will automatically feed the buffered audio data into the SR engine, ensuring that no real-time audio data is lost and that the user experience is not interrupted.
However, the SAPI audio buffer has a static limit (see ISpMMSysAudio::Read) to prevent large amounts of system memory from being consumed by SAPI applications or SR engines. Therefore, Pause should be used by the SR engine for very short periods of time for state changes (for example, updating grammar, or rule states). Pausing the SR engine will affect all recognition contexts connected to that SR engine including other running Speech applications.
If the SR engine is paused too long, and the audio buffer is filled, a buffer overflow will occur. The application can detect this error by setting an event interest in SPEI_END_SR_STREAM (see SPEVENTENUM), and checking the LPARAM of the SPEVENT structure (see CSpEvent::EndStreamResult).
SAPI will automatically attempt to restart the SR engine's recognition thread once the final Resume has been called. Consequently, the audio data collected between the point when the buffer overflow occurred, and when the stream was reactivated, will be completely lost. This would result in a less than optimal user experience, and have a negative effect on all running speech applications, the SR engine, and SAPI.
Example
The following code snippet illustrates the use of this method.
HRESULT hr = S_OK;
// setup the recognition context
// ...
// pause the context so that event notifications are not received
hr = cpRecoContext->Pause( NULL );
// Check hr
// [quickly] perform the processing - see ISpRecoContext::Pause Remarks section
// ...
hr = cpRecoContext->Resume( NULL );
// Check hr
// applications will start receiving event notifications again
Requirements
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |