IAgentCharacterEx::GetSRStatus

[Microsoft Agent is deprecated as of Windows 7, and may be unavailable in subsequent versions of Windows.]

HRESULT GetSRStatus(
   long * plStatus  // address of the speech input status
);

Retrieves the status of the condition necessary to support speech input.

• Returns S_OK to indicate the operation was successful.

plStatus

Address of a variable that receives one of the following values for the state setting:

Value	Description
const unsigned long LISTEN_STATUS_CANLISTEN = 0;	Conditions support speech input.
const unsigned long LISTEN_STATUS_NOAUDIO = 1;	There is no audio input device available on this system. (Note that this does not detect whether a microphone is installed; it can only detect whether the user has a properly installed input-enabled sound card with a working driver.)
const unsigned long LISTEN_STATUS_NOTTOPMOST = 2;	Another client is the active client of this character, or the current character is not topmost.
const unsigned long LISTEN_STATUS_CANTOPENAUDIO = 3;	The audio input or output channel is currently busy, some other application is using audio.
const unsigned long LISTEN_STATUS_COULDNTINITIALIZESPEECH = 4;	An unspecified error occurred in the process of initializing the speech recognition subsystem. This includes the possibility that there is no speech engine available matching the character's language setting.
const unsigned long LISTEN_STATUS_SPEECHDISABLED = 5;	The user has disabled speech input in the Advanced Character Options window.
const unsigned long LISTEN_STATUS_ERROR = 6;	An error occurred in checking the audio status, but the cause of the error was not returned by the system.

This function enables you to query whether current conditions support speech recognition input, including the status of the audio device. If your application uses the IAgentCharacterEx::Listen method, you can use this function to better ensure that the call will succeed. Calling this method also loads the speech engine if it is not already loaded. However, it does not turn on Listening mode.

When speech input is enabled in the Agent property sheet (Advanced Character Options), querying the status will load the associated engine (if it is not already loaded), and start speech services. That is, the Listening key is available, and the Listening Tip is displayable. (The Listening key and Listening Tip are enabled only if they are also enabled in Advanced Character Options.) However, if you query the property when speech is disabled, the server does not start speech services.

This function returns only the setting for your client application's use of the character; the setting does not reflect other clients of the character or other characters of your client application.