ISpRecoGrammar::SetGrammarState

Microsoft Speech SDK

The Microsoft.com Speech website Microsoft Speech SDK SAPI 5.1

ISpRecoGrammar::SetGrammarState

ISpRecoGrammar::SetGrammarState sets the grammar state.

HRESULT SetGrammarState(
   SPGRAMMARSTATE   eGrammarState
);

Parameters

eGrammarState
[in] Flag of type SPGRAMMARSTATE indicating the new state of the grammar.

Return values

Value Description
S_OK Function completed successfully.
E_INVALIDARG eGrammarState is not a valid state.
FAILED(hr) Appropriate error message.

Remarks

If eGrammarState is SPGM_DISABLED, SAPI will retain the current rule activation state, so that when the grammar state is set to SPGM_ENABLED, it restores the grammar rules back to each of the original activation states. While the grammar is set to SPGM_DISABLED, the application can still activate and deactivate rule. The effect is not communicated to the SR engine (but retained by SAPI) until the grammar is enabled again.

If eGrammarState is SPGM_EXCLUSIVE, SAPI will disable all other grammars in the system, unless another grammar is already exclusive. Activation and deactivation commands are buffered for all other grammars until the exclusive grammar is set to SPGM_ENABLED again.

The default grammar state is SPGS_ENABLED, meaning the grammar can receive recognitions.

Applications can use the grammar state to control whether it will receive recognitions for rules in that SpRecoGrammar object. For example, an application create a new SpRecoGrammar object, set the grammar state to SPGS_DISABLED, dynamically generate the rules, and finally set the grammar state to SPFS_ENABLED when grammar construction is completed.

See also ISpRecoGrammar::GetGrammarState.

Example

The following code snippet illustrates the use of ISpRecoGrammar::SetGrammarState to set  the state of an grammar

    HRESULT hr = S_OK;

    // create a new grammar object
    hr = cpRecoContext->CreateGrammar(GRAM_ID, &cpRecoGrammar);
    // Check hr

    // disable the grammar, so that recognitions are not received
    hr = cpRecoGrammar->SetGrammarState(SPGS_DISABLED);
    // Check hr

    // ... build the grammar ...

    // activate the grammar, so applications start receiving recognitions
    hr = cpRecoGrammar->SetGrammarState(SPGS_ENABLED);
    // Check hr