ISpSREngineSite::Synchronize
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 synchronizes to changes in grammars. It is called by the SR engine when it is ready to process changes. This method can only be called while the SR engine is inside a ISpSREngine::RecognizeStream call, although it can be called on any thread.
If there are any changes pending, ISpSREngineSite::Synchronize calls back to the engine using ISpSREngine::WordNotify or ISpSREngine::RuleNotify. When the engine returns from the notification method, Synchronize returns. If the return code is S_FALSE, and there are no more active rules, the engine is free to exit the current call to ISpSREngine::RecognizeStream without reading or processing more data.
Syntax
HRESULT Synchronize(
ULONGLONG ullStreamPos
);
Parameters
- ullStreamPos
[in] Position in the audio stream at which the engine has completed recognition. SAPI discards its stored audio up to this point. The engine cannot fire more events prior to this position. However, the engine will still be informed of current grammar changes, regardless of the value of the parameter.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully, and the engine can continue recognition. |
S_FALSE |
Function completed successfully, and the engine can terminate recognition without reading the rest of the stream. |
SPERR_STREAM_NOT_ACTIVE |
Stream is not initialized. |
SPERR_STREAM_POS_INVALID |
Stream position is either more than the current seek position or less than the last synchronized position. |
FAILED(hr) |
Appropriate error message. |
Remarks
An engine can choose when to call ISpSREngineSite::Synchronize. Often an engine will respond to state changes when no speech is detected, but it will not respond when the user is speaking. Therefore it is important for the engine to periodically call Synchronize. Specifically, if an application attempts to release its final reference to SAPI, and no other applications are connected, SAPI attempts to shut down the SR engine. However, the shutdown process waits indefinitely for the SR engine to reach its next synchronization point and call Synchronize.
An example of synchronization for the user is the start of dictation mode and activation of a non-silence noise source in the background that generates a single continuous recognition. When the user attempts to exit the application, the exit is blocked until the SR engine finishes recognizing the audio stream.
Periodic calls to Synchronize prevent extended delays in state changes (for example, application shutdown, grammar changes, and so on), even when performing a long recognition. This ensures that the SR engine is able to properly clean up and exit its ISpSREngine::RecognizeStream method.
Requirements
| Header | sapiddk.h, sapiddk.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |