Export (0) Print
Expand All

ISpRecoGrammar::SetRuleIdState (SAPI 5.3)

Speech API 5.3
Microsoft Speech API 5.3

ISpRecoGrammar::SetRuleIdState

ISpRecoGrammar::SetRuleIdState activates or deactivates a rule by its rule ID.

HRESULT SetRuleIdState(
   ULONG         ulRuleId,
   SPRULESTATE   NewState
);

Parameters

ulRuleId
[in] Value specifying the grammar rule identifier. If zero, all rules with attribute SPRAF_TopLevel and SPRAF_Active and set (at rule creation time) are affected.
NewState
[in] Flag of type SPRULESTATE indicating the new rule state.

Return values

ValueDescription
S_OKFunction completed successfully.
E_INVALIDARGdwRuleId is invalid.
SP_STREAM_UNINITIALIZEDISpRecognizer::SetInput has not been called with the InProc recognizer.
SPERR_UNINITIALIZEDThe object has not been properly initialized.
SPERR_UNSUPPORTED_FORMATAudio format is bad or is not recognized. Alternatively, the device driver may be busy by another application and cannot be accessed.
SPERR_DEVICE_BUSYThe audio
SPERR_NOT_TOPLEVEL_RULEThe rule ID ulRuleId exists, but is not a top-level rule.
FAILED(hr)Appropriate error message.

Remarks

An application can use the SPRS_ACTIVE_WITH_AUTO_PAUSE state to pause the engine after each dictation 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).

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

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

By default, the recognizer state (SPRECOSTATE) is SPRST_ACTIVE, which means that recognition will begin as soon as dictation is activated. Consequently, an application should not activate the dictation 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 dictation topics.

If the recognizer state is SPRST_ACTIVE, SAPI will first attempt to open the audio input stream when a rule (or dictation) 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 ::SetRuleIdState. 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 the dictation topic state.

Example

The following code snippet illustrates the use of ISpRecoGrammar::SetRuleIdState by programmatically creating a rule and activating it


// Declare local identifiers:
HRESULT                      hr = S_OK;
CComPtr<ISpRecoGrammar>      cpRecoGrammar;
SPSTATEHANDLE                hState;

// Create a new rule.
hr = cpRecoGrammar->GetRule(L"Travel", 1, SPRAF_TopLevel | SPRAF_Active, TRUE, &hState;);

if (SUCCEEDED(hr))
{
   // ... Add word transitions ...

   // Activate the rule by its Id.
   hr = cpRecoGrammar->SetRuleIdState(1, SPRS_ACTIVE);
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}
Show:
© 2014 Microsoft