Partager via

ISpSREngineSite::Synchronize (SAPI 5.3)

  • Article

Microsoft Speech API 5.3

ISpSREngineSite::Synchronize

ISpSREngineSite::Synchronize informs SAPI that the engine is ready to process changes in its grammars.

  
    HRESULT Synchronize(
   ULONGLONG   ullStreamPos
);

Parameters

  • ullStreamPos
    [in] The position within the audio stream that the engine has completed recognizing. 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 values

Value
S_OK
S_FALSE
SPERR_STREAM_NOT_ACTIVE
SPERR_STREAM_POS_INVALID
FAILED (hr)

Remarks

If there are any changes pending, SAPI will call back to the engine to inform it of any changes using WordNotify or RuleNotify. When the engine returns from these methods, SAPI will return back from the Synchronize call. If the return value from this call is S_FALSE, and there are no more active rules, the engine is free to exit the RecognizeStream call without reading or processing more data.

The engine can choose when to call Synchronize. Often an engine will respond to state changes when no speech is detected, but it will not respond when the user is speaking. It is important, however, to periodically, if not routinely, call Synchronize. Specifically, if an application attempts to release its final reference to SAPI, and no other applications are connected, SAPI will attempt to shutdown the SR engine. However, the shutdown process will wait indefinitely for the SR engine to reach its next synchronization point (e.g., the speech recognition engine calls ISpSREngineSite::Synchronize).

This method can only be called while the SR engine is inside a ISpSREngine::RecognizeStream call, although it can be called on any thread. For more details on this method, see the SR Engine Guide.

An example of the synchronization for the user would be starting dictation mode, and activating a non-silence noise source in the background that will generate a single continuous recognition. When the user attempts to exit the application, the exit will be blocked until the SR engine finishes recognizing the audio stream. For this reason, the SR engine should call ISpSREngineSite::Synchronize periodically to prevent extended delays in state changes (e.g., application shutdown, grammar changes, etc.), even when performing a long recognition. This ensures that the SR engine is able to properly clean up and exit its ISpSREngine::RecognizeStream method.