IVCmdAttributes::AwakeStateSet

This method sets the awake state for a voice command site.

Syntax

HRESULT AwakeStateSet( DWORD dwAwake );

Parameters

dwAwake

[in] Specifies whether the awake state of the voice command site. Set to TRUE to cause the site to wake up, or to FALSE to cause it to go to sleep.

Return Values

NOERROR

The method successfully set the awake state for a voice command site.

E_INVALIDARG

The argument is invalid.

VCMDERR_INVALIDMODE

No site exists, the site does not support this attribute, or the voice command object is already registered with a site.

VCMDERR_OUTOFMEM

There is no more memory.

VCMDERR_VALUEOUTOFRANGE

The value is out of range.

Remarks

If a voice navigation application is installed on the user’s computer, suspending speech recognition by using AwakeStateSet typically causes the voice navigation application to activate a “wake up” menu.

Calling AwakeStateSet allows the user to temporarily suspend speech recognition for a site. For example, the user might want to suspend speech recognition from the computer microphone during a telephone conversation and resume recognition when the conversation is finished. The user resumes recognition by speaking an appropriate command from a sleep menu—for example, “Wake up.”

The sleep state for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

If a voice navigation application is installed on the user’s computer, an application may not need to set the sleep state. However, it may call this method to verify that speech recognition is awake. For example, if an application asks—using with voice text or text-to-speech—”Do you want to print the document?” it might enable and wake up speech recognition for the site to receive the user’s reply. The application should then restore speech recognition to its previous state.