ISpRecoContext::SetVoicePurgeEvent (SAPI 5.4)

Speech API 5.4
Microsoft Speech API 5.4

ISpRecoContext::SetVoicePurgeEvent

ISpRecoContext::SetVoicePurgeEvent sets the SR engine events that stop audio output, and purges the current speaking queue.

HRESULT SetVoicePurgeEvent(
   ULONGLONG   ullEventInterest
);

Parameters

ullEventInterest
[in] The set of flags indicating the event interest(s). The event interest(s) must be in the set of speech recognition events (i.e., between SPEI_MIN_SR and SPEI_MAX_SR) (see SPEVENTENUM and SPFEI_ALL_SR_EVENTS)

Return values

ValueDescription
S_OKFunction completed successfully.
E_INVALIDARGOne or more of the event interests set is not allowed.
FAILED(hr)Appropriate error message.

Remarks

The ISpRecoContext event interest will be updated to include the Voice Purge Events (see ISpEventSource::SetInterest).

To find the current Voice Purge Event(s), use ISpRecoContext::GetVoicePurgeEvent

Applications can call SetVoicePurgeEvent when implementing "barge-in" type functionality. For example, when a user calls a telephony server, and the server uses TTS Voice prompts, the Voice should stop speaking when the user is speaking. The application would want the associated Voice object of the ISpRecoContext (see ISpRecoContext::GetVoice) to stop and purge when the SR engine hears a sound (see SPEI_SOUND_START).

Example

The following code snippet illustrates the use of ISpRecoContext::SetVoicePurgeEvent and "barge-in" setup


// Declare local identifiers:
HRESULT	                   hr = S_OK;
CComPtr<ISpRecoContext>    cpRecoContext;
CComPtr<ISpVoice>          cpVoice;

// Create a shared recognition context.
hr = cpRecoContext.CoCreateInstance(CLSID_SpSharedRecoContext);

if (SUCCEEDED(hr))
{
   // Create a voice from the context (with
   // same audio format as context).
   hr = cpRecoContext->GetVoice(&cpVoice;);
}

if (SUCCEEDED(hr))
{
   // Tell the associated Voice to stop speaking when
   // the SR Engine hears a recognizable sound.
   hr = cpRecoContext->SetVoicePurgeEvent(SPFEI(SPEI_SOUND_START));
}

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