ISpRecoGrammar::SetRuleIdState (Windows CE 5.0)

Article
09/14/2012

This method starts or stops a rule by its rule identifier. The identifier is specified in the XML grammar (using the rule identifier tag). Alternatively the identifier is specified when ISpGrammarBuilder::GetRule is called. See also ISpSREngine::RuleNotify for information on the how SAPI notifies the SR engine about the rule identifier state.

HRESULT SetRuleIdState(ULONG ulRuleId,SPRULESTATE NewState);

Parameters

ulRuleId
[in] Grammar rule identifier. If zero, all rules with attribute SPRAF_TopLevel and SPRAF_Active and set (at rule creation time) are affected.
NewState
[in] Value identifying the grammar rule state. Possible values are defined for the SPRULESTATE enumeration.

Return Values

The following table shows the possible return values.

Value	Description
S_OK	Function completed successfully.
E_INVALIDARG	dwRuleId is invalid.
SP_STREAM_UNINITIALIZED	ISpRecognizer::SetInput has not been called with the inproc recognizer.
SPERR_UNINITIALIZED	The object has not been properly initialized.
SPERR_UNSUPPORTED_FORMAT	Audio format is bad or is not recognized. Alternatively, the device driver may be busy by another application and cannot be accessed.
SPERR_DEVICE_BUSY	The audio
SPERR_NOT_TOPLEVEL_RULE	The rule identifier ulRuleId exists, but is not a top-level rule.
FAILED(hr)	Appropriate error message.

Remarks

By default, the recognizer state (SPRECOSTATE) is SPRST_ACTIVE and recognition begins as soon as dictation is activated. Consequently, an application should not activate the dictation grammar rule state until it is prepared to receive recognitions. With the recognizer state set to SPRST_ACTIVE, SAPI first attempts 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 retrieved by ISpRecoGrammar::SetRuleIdState. The application should handle this failure gracefully.

The application can use the SPRS_ACTIVE_WITH_AUTO_PAUSE state for the NewState parameter to pause the engine after each dictation recognition is sent. The application must restart the SR engine using ISpRecoContext::Resume to prevent the loss of input audio data. See also ISpSREngineSite::Read.

The application can also disable the grammar objects or the recognition context object (ISpRecoContext) to prevent recognitions from being fired for active dictation topics.

If an application uses an InProc recognizer, it must call ISpRecognizer::SetInput with a non-null setting before the recognizer will retrieve recognitions. This call must be made regardless of the dictation topic state.

Example

The following code snippet illustrates the use of this method by programmatically creating a rule and activating it.

HRESULT hr = S_OK;
// create a new rule
SPSTATEHANDLE hStateTravel;
hr = cpRecoGrammar->GetRule(MYRULENAME, MY_RULE_ID, SPRAF_TopLevel |
SPRAF_Active, TRUE, &hState);
// Check hr
// .. add word transitions...
// start the rule by its identifier
hr = cpRecoGrammar->SetRuleIdState(MY_RULE_ID, SPRS_ACTIVE);
// Check hr

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.

Share via