ISpRecoGrammar::SetRuleState (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

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.

Syntax

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 Value

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

Header	sapi.h, sapi.idl
Library	sapilib.lib
Windows Embedded CE	Windows CE .NET 4.1 and later

Share via