ISpRecoGrammar::SetGrammarState (SAPI 5.4)

Microsoft Speech API 5.4

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

Remarks

If eGrammarState is SPGS_DISABLED, SAPI will retain the current rule activation state, so that when the grammar state is set to SPGS_ENABLED, it restores the grammar rules back to each of the original activation states. While the grammar is set to SPGS_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 SPGS_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 SPGS_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

  
// Declare local identifiers:
HRESULT                      hr = S_OK;
CComPtr<ISpRecoGrammar>      cpRecoGrammar;
CComPtr<ISpRecoContext>      cpRecoContext;
ULONGLONG                    ullGramId = 1;

// Create a new grammar object.
hr = cpRecoContext->CreateGrammar(ullGramId, &cpRecoGrammar;);

if (SUCCEEDED(hr))
{
   // Disable the grammar so that recognitions are not received.
   hr = cpRecoGrammar->SetGrammarState(SPGS_DISABLED);
}

if (SUCCEEDED(hr))
{
   // ... Build the grammar ...

   // Activate the grammar so applications start receiving recognitions.
   hr = cpRecoGrammar->SetGrammarState(SPGS_ENABLED);
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}