Microsoft Speech Platform

ISpRecoGrammar::SetRuleIdState

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

<pre IsFakePre="true" xmlns="http://www.w3.org/1999/xhtml"> HRESULT SetRuleIdState( ULONG ulRuleId, <a runat="server" href="jj127477(v=msdn.10).md">SPRULESTATE</a> NewState ); </pre>

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

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

Remarks

The ulRuleId parameter takes an integer value that the Speech Platform assigns as an identifier to each rule when it is loaded to the SpRecoGrammar object.

By default, the recognizer state (SPRECOSTATE) is SPRST_ACTIVE, which means that if a rule is active, audio will be read and passed to the speech recognition (SR) engine and recognition will happen. Consequently, an application should not activate a rule 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, the Speech Platform will first attempt to open the audio input stream when a rule is activated. Consequently, if the audio device is already in use by another context, or the stream fails to open, the failure code will be returned using ::SetRuleIdState. The application should handle this failure gracefully.

An application must call ISpRecognizer::SetInput with a non-NULL setting before the recognizer will return recognitions, regardless of the rule 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.
}

Share via