Microsoft Speech Platform

---

ISpRecoGrammar::SetDictationState

ISpRecoGrammar::SetDictationState sets the dictation topic state.

The dictation topic is specified by calling ISpRecoGrammar::LoadDictation.

HRESULT SetDictationState(
   SPRULESTATE   NewState
);

Parameters

NewState

[in] Flag of type SPRULESTATE indicating the new state of dictation. See Remarks section

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 reactivate the SR engine (see ISpRecoContext::Resume) to prevent the loss of input audio data (see SPERR_AUDIO_BUFFER_OVERFLOW).

By default, the recognizer state (SPRECOSTATE) is SPRST_ACTIVE, which means that recognition will begin as soon as dictation is activated. Consequently, an application should not activate 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, SAPI will first attempt to open the audio input stream when dictation (or a rule) 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 returned 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 return recognitions, regardless of the dictation topic state.

Example

The following code snippet illustrates the use of ISpRecoGrammar::SetDictationState to load a spelling topic and activate it.

// Declare local identifiers:
HRESULT                      hr = S_OK;
CComPtr<ISpRecoGrammar>      cpRecoGrammar;
CComPtr<ISpRecoContext>      cpRecoContext;
ULONGLONG                    ullGramId = 1;

// Create a grammar object.
hr = cpRecoContext->CreateGrammar(ullGramId, &cpRecoGrammar;);

if (SUCCEEDED(hr))
{
   // Load the general dictation topic.
   hr = cpRecoGrammar->LoadDictation(NULL, SPLO_STATIC);
}

if (SUCCEEDED(hr))
{
   // Activate the dictation topic to receive recognitions.
   hr = cpRecoGrammar->SetDictationState(SPRS_ACTIVE);
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}