ISpRecoContext::GetStatus (SAPI 5.4)

Microsoft Speech API 5.4

ISpRecoContext::GetStatus

ISpRecoContext::GetStatus retrieves current state information associated with a context (e.g., last SR engine requested UI, audio signal status, etc.).

  
    HRESULT GetStatus(SPRECOCONTEXTSTATUS   *pStatus
);

Parameters

• pStatus
  [out] Address of the SPRECOCONTEXTSTATUS structure that receives the context state information.

Return values

Remarks

A graphical application that is interested in SPEI_REQUEST_UI events from the SR engine can call ISpRecoContext::GetStatus, and check the szRequestTypeOfUI field to check the last requested UI-type. After the application has called ISpRecognizer::DisplayUI, the SR engine can clear the szRequestTypeOfUI field by calling ISpSREngineSite::AddEvent with a NULL UI-type.

An application can also periodically query the recognition context status to check the audio signal quality (see also SPINTERFERENCE) and respond appropriately. An application can prompt the user to access the SR engine's microphone training UI to improve the audio signal quality (see SPDUI_MicTraining), or prompt the user to modify the audio settings using Speech properties in Control Panel (see SPDUI_AudioProperties and SPDUI_AudioVolume).

Example

The following code snippet illustrates the use of ISpRecoContext::GetStatus for responding to SR engine UI requests.

  
// Declare local identifiers:
HRESULT                    hr = S_OK;
CComPtr<ISpRecoContext>    cpRecoContext;
CComPtr<ISpRecognizer>     cpRecognizer;
SPRECOCONTEXTSTATUS        contextStatus;
BOOL                       fSupported;
	
// Assume UI request [SPEI_REQUEST_UI] has been received.

// Check what kind of UI the SR Engine wants.
hr = cpRecoContext->GetStatus(&contextStatus;);

if (SUCCEEDED(hr))
{
   // Get a reference to the SR Engine.
   hr = cpRecoContext->GetRecognizer(&cpRecognizer;);
}

if (SUCCEEDED(hr))
{
   // Sanity check that the UI type is supported.
   hr = cpRecognizer->IsUISupported(contextStatus.szRequestTypeOfUI, NULL, NULL, &fSupported;);
}

if (SUCCEEDED(hr))
{
   // Ask the SR engine to display the UI and use the default window title.
   hr = cpRecognizer->IsUISupported(contextStatus.szRequestTypeOfUI, NULL, NULL, &fSupported;);
}

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