ISpRecoGrammar::SetDictationState (Windows Embedded CE 6.0)
1/6/2010
This method sets the dictation topic state. The dictation topic is specified by calling ISpRecoGrammar::LoadDictation. See also ISpSREngine::SetSLMState for information on how SAPI notifies the SR engine.
Syntax
HRESULT SetDictationState(
SPRULESTATE NewState
);
Parameters
- NewState
[in] Value identifying the grammar rule (or dictation topic) state. Possible values are defined for the SPRULESTATE enumeration. See Remarks section.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
E_INVALIDARG |
NewState is not an acceptable value. |
SP_STREAM_UNINITIALIZED |
ISpRecognizer::SetInput has not been called with the InProc SR engine. |
SPERR_UNINITIALIZED |
A dictation is not currently loaded. |
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. |
FAILED(hr) |
Appropriate error message. |
Remarks
An application can use the SPRS_ACTIVE_WITH_AUTO_PAUSE state to pause the engine after each dictation recognition is sent. The application must restart the SR engine (see ISpRecoContext::Resume) to prevent the loss of input audio data (see ISpSREngineSite::Read and SPERR_AUDIO_BUFFER_OVERFLOW).
By default, the recognizer state (SPRECOSTATE) is SPRST_ACTIVE, which means that recognition will begin as soon as dictation is started. Consequently, an application should not start the dictation state 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 dictation topics.
If the recognizer state is SPRST_ACTIVE, then SAPI will first attempt to open the audio input stream when dictation (or a rule) is started. Consequently, if the audio device is already in use by another application, or the stream fails to open, the failure code will be retrieved using SetDictationState. The application should handle this failure gracefully.
If an application uses an InProc recognizer, it must call ISpRecognizer::SetInput with a non-null setting before the recognizer will retrieve recognitions, regardless of the dictation topic state.
Example
The following code snippet illustrates the use of this method to load a spelling topic and start it.
HRESULT hr = S_OK;
// create a grammar object
hr = cpRecoContext->CreateGrammar(GRAM_ID, &cpRecoGrammar);
// Check hr
// load the general Dictation topic
hr = cpRecoGrammar->LoadDictation(NULL, SPLO_STATIC);
// Check hr
// start the Dictation topic to receive recognitions
hr = cpRecoGrammar->SetDictationState(SPRS_ACTIVE);
// check hr
Requirements
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |