Microsoft Speech Platform

ISpRecoGrammar::SetRuleState

ISpRecoGrammar::SetRuleState activates or deactivates a top-level rule by its rule name.

<pre IsFakePre="true" xmlns="http://www.w3.org/1999/xhtml"> <strong>HRESULT SetRuleState(</strong> <strong> LPCWSTR</strong> <em>pszName</em>, <strong> void </strong> *<em>pReserved</em>, <a runat="server" href="jj127477(v=msdn.10).md"><strong>SPRULESTATE</strong></a> <em>NewState</em> <strong>);</strong> </pre>

Parameters

• pszName
  [in, string] Address of a null-terminated string containing the rule name. If NULL and the grammar was created using ISpGrammarBuilder, all rules with attribute SPRAF_TopLevel and SPRAF_Active and set (at rule creation time) are affected. If the grammar is SRGS XML, use the value of the root rule's id attribute, or NULL, to activate the grammar.
• pReserved
  Reserved. Do not use; must be NULL.
• NewState
  [in] Flag of type SPRULESTATE indicating the new rule state. See Remarks section.

Return Values

Remarks

Use SetRuleState for grammars created programmatically with ISpGrammarBuilder , or for XML-format grammars that conform to the Speech Recognition Grammar Specification (SRGS) Version 1.0.

If the grammar is SRGS XML, use the value of the root rule's id attribute for pszName. The rule name is specified by the pszRuleName attribute when ISpGrammarBuilder::GetRule is called.

Grammars created using ISpGrammarBuilder can have multiple top-level rules. Top-level rules are the entry points into the grammar. SetRuleState allows you to programmatically activate and deactivate individual top-level rules.

Be sure that you use the correct letter casing when specifying the rule name. Rule names are case-sensitive in the Speech Platform. For example, if the name of the rule to target is "Test", and you set the value of pszName to "test", the call will generate an error or incorrectly target a rule named "test".

An XML-format SRGS grammar can have only a single entry point - the root rule of the grammar. When you activate or deactivate the root rule, you activate or deactivate the grammar. For SRGS XML grammrs, using SetRuleState to activate or deactivate the root rule has the same effect as calling ::SetGrammarState and setting the SPGS_ENABLED or SPGS_DISABLED flag.

An application can use the SPRS_ACTIVE_WITH_AUTO_PAUSE state to pause the engine after each recognition is sent. The application must reactivate the SR engine (see ISpRecoContext::Resume) to prevent the loss of input audio data (see SPERR_AUDIO_BUFFER_OVERFLOW).

By default, the recognizer state (SPRECOSTATE) is SPRST_ACTIVE, and the recognition will begin as soon as one or more rules are activated. Consequently, an application should not activate the rule state until it is prepared to receive recognitions. An application can also disable the SpRecoContext object (see ISpRecoContext::SetContextState) or SpRecoGrammar objects (see ISpRecoGrammar::SetGrammarState) to prevent recognitions from being fired for active rules. 

If the recognizer state is SPRST_ACTIVE, the Speech Platform will first attempt to open the audio input stream when a rule is activated. Consequently, if the audio device is already in use, for example by another ISpRecoContext, or the stream fails to open, the failure code will be returned using ::SetRuleState. The application should handle this failure gracefully.

An application must call ISpRecognizer::SetInput with a non-NULL setting before the recognizer will return recognitions, regardless of how many rules are active.

Example

The following snippet loads a grammar, activate a single rule ("playcard") and then immediately deactivates it.

`

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

// Create a grammar object.
hr = cpRecoContext->CreateGrammar(ullGramId, &cpRecoGrammar;);
if (SUCCEEDED(hr))
{
// Activate the rule.
hr = cpRecoGrammar->SetRuleState(L"playcard", NULL, SPRS_ACTIVE);
}
if (SUCCEEDED(hr))
{
// Deactivate the rule.
hr = cpRecoGrammar->SetRuleState(L"playcard", NULL, SPRS_INACTIVE);
}
if (SUCCEEDED(hr))
{
// Do stuff here.
}