HRESULT Activate(HWND hWndListening, BOOL fAutoPause, PTCHAR pszInfo);
Activates a grammar so that the speech-recognition engine can begin using the grammar to recognize speech.
· Returns NOERROR if successful, or one of these error values:
E_INVALIDARG
E_OUTOFMEMORY
SRERR_GRAMMARTOOCOMPLEX
SRERR_INVALIDRULE
SRERR_INVALIDWINDOW
SRERR_RULEALREADYACTIVE
hWndListening
[in] Handle of the window for which this grammar should be used for recognition. This window is compared against the window returned by the GetForegroundWindow function at the beginning of the speech. If the windows match, the grammar is used; if they don't match, the grammar is not used. If hWndListening is NULL, the grammar is used continuously, which allows the application to recognize a global vocabulary. However, in case of a recognition conflict, a grammar whose hWndListening parameter is NULL has a lower priority than a grammar whose hWndListening parameter matches the foreground window. If the window is invalid, the member function returns E_INVALIDARG.
fAutoPause
[in] TRUE if the engine should automatically pause when this grammar is involved in a recognition (whether successful or unsuccessful) and send a PhraseFinish notification to the application. FALSE if the engine should not pause for this grammar. (The engine pauses once for any grammar for which this parameter is TRUE.) Even if more than one rule of a context-free grammar is active, this still increases the pause count by only 1.
pszInfo
[in] For a dictation or limited-domain grammar, this parameter is not used and should be NULL. For a context-free grammar, this parameter points to the name of the rule to activate. If the rule is already activated, this parameter is ignored. More than one rule can be active at a time; however, too many active rules can diminish recognition accuracy. If pszInfo is NULL for a context-free grammar, it activates the rule that has the rule name of "Start." If the rule is already active, the Activate member function returns an error.
Many engines restrict the number and type of grammars that can be active at the same time. Typically, an engine allows many context-free grammars but only one dictation or limited-domain grammar to be active at a time.
Because speaking is asynchronous, changes to the active grammar must be made before the speaker begins to speak. Changing the active grammar during speech may not have any effect until after the utterance ends. In addition, the engine may respond as if it has activated a grammar and postpone its real activation until an opportune time, such as when an utterance stops.
If any rule in a grammar has the auto-pause flag set, and the grammar has at least one rule active, the pause count is increased by 1 after a PhraseFinish notification. If multiple rules have the auto-pause flag set, the pause count is still increased only by 1. Likewise, only one ISRGramNotifySink::Paused notification is sent, even if more than one rule has the auto-pause flag set.