ISpRecoGrammar::SetRuleState (SAPI 5.4)

Microsoft Speech API 5.4

ISpRecoGrammar::SetRuleState

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

  
    HRESULT SetRuleState(
   LPCWSTR       pszName,
   void          *pReserved,
SPRULESTATE    NewState
);

Parameters

• pszName
  [in, string] Address of a null-terminated string containing the rule name. If NULL and the grammar is in SAPI 5 format, all rules with attribute SPRAF_TopLevel and SPRAF_Active and set (at rule creation time) are affected.
• pReserved
  Reserved. Do not use; must be NULL.
• NewState
  [in] Flag of type SPRULESTATE indicating the new rule state. See Remarks section.

Return values

Value

S_OK

E_INVALIDARG

SP_STREAM_UNINITIALIZED

SPERR_UNINITIALIZED

SPERR_UNSUPPORTED_FORMAT

SPERR_NOT_TOPLEVEL_RULE

FAILED(hr)

Remarks

The rule name is specified in the XML grammar (using the rule NAME tag), or when ISpGrammarBuilder::GetRule is called.

See also ISpSREngine::RuleNotify for information on the how SAPI notifies the SR engine.

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

By default, the recognizer state (SPRECOSTATE) is SPRST_ACTIVE, and the recognition will begin as soon as one or more rule 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, SAPI will first attempt to open the audio input stream when dictation (or a rule) is activated. Consequently, if the audio device is already in use by another application, or the stream fails to open, the failure code will be returned using ::SetRuleState. The application should handle this failure gracefully.

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

Be sure that you use the correct letter casing when specifying the rule name. Rule names are case-sensitive in SAPI. 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".

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.
}