ISpRecoGrammar::SetRuleIdState (Windows Embedded CE 6.0)
1/6/2010
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.
Syntax
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 Value
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
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |