ISpRecoGrammar::SetRuleState (Windows CE 5.0)
This method starts or stops a rule by its rule name. The rule name is specified in the XML grammar (using the rule NAME tag). Alternatively it is specified when ISpGrammarBuilder::GetRule is called. See also ISpSREngine::RuleNotify for information on the how SAPI notifies the SR engine.
HRESULT SetRuleState(const WCHAR* pszName,void* pReserved,SPRULESTATE NewState);
Parameters
- pszName
[in] Pointer to a null-terminated string specifying the rule name. If NULL, all rules with attributes SPRAF_TopLevel and SPRAF_Active and set (at rule creation time) are affected. - pReserved
Reserved. Do not use. Must be NULL. - 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 | pszName is invalid or bad. Alternatively, pReserved is non-null. |
| 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_NOT_TOPLEVEL_RULE | The rule pszName 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 one or more rules are started. Consequently, an application should not start the 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::SetRuleState. The application should handle this failure gracefully.
An application can also disable the SpRecoContext object (see The application can use the SPRS_ACTIVE_WITH_AUTO_PAUSE state for the NewState parameter to pause the engine after each CFG 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 rule states.
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 how many rules are active.
Example
The following snippet loads a grammar, starts a single rule ("playcard") and then immediately stops the rule.
HRESULT hr;
// create a grammar object
hr = cpRecoContext->CreateGrammar(GRAM_ID, &cpRecoGrammar);
//Check return value
// start the rule
hr = cpRecoGrammar->SetRuleState(L"playcard", NULL, SPRS_ACTIVE);
//Check return value
//Stop the rule
hr = cpRecoGrammar->SetRuleState(L"playcard", NULL, SPRS_INACTIVE);
//Check return value
Requirements
OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.
See Also
ISpRecoGrammar | SAPI Interfaces
Send Feedback on this topic to the authors