Initializing an Application for Voice Commands

To use voice commands, you need to create a voice-command object, register your application with the object, and then create a voice-menu object to manage your application's voice menus. You create a voice-command object by calling the CoCreateInstance function with the CLSID_VCmd class identifier and the IID_IVoiceCmd interface identifier. You must create a separate voice-command object for each site that your application needs to use.

CoCreateInstance returns a pointer to the IVoiceCmd interface for the voice-command object. Before it can perform other voice-command tasks, an application must register itself by calling the IVoiceCmd::Register member function. Register specifies the site that the object represents, and passes the address of the application's voice-command notification interface to the voice-command object.

After creating a voice-command object and registering the application, you can use the IVoiceCmd::MenuCreate member function to open a voice menu and create a voice-menu object to represent the menu. MenuCreate retrieves the address of the IVCmdMenu interface for the voice-menu object. You can use the interface's member functions to manage the menu and its commands.

The following example shows how to create a voice-command object, register an application, and create a voice-menu object. The example creates a temporary voice-menu object; that is, the object is not added to the voice-menu database maintained by the voice-command object.

// BeginOLE - initializes OLE, creates an instance of the voice-command

// object, registers the application with the object, and creates a

// temporary voice-menu object.

// Returns TRUE if successful or FALSE otherwise.

//

// Global variables and constants:

// gpIVoiceCommmand - address of the IVoiceCmd interface for the

// voice-command object

// gpIVCmdDialogs - address of the IVCmdDialog interface for the

// voice-command object

// gpIVCmdMenu - address of the IVCmdMenu interface for the

// voice-menu object

BOOL BeginOLE (void)

{

HRESULT hRes;

VCMDNAME VcmdName;

LANGUAGE Language;

PIVCMDATTRIBUTES pIVCmdAttributes;

// Initialize interface pointers to NULL.

gpIVoiceCommand = NULL;

gpIVCmdDialogs = NULL;

gpIVCmdMenu = NULL;

// Initialize OLE.

if (FAILED(CoInitialize(NULL)))

return FALSE;

// Create the voice-command object.

if (CoCreateInstance(CLSID_VCmd, NULL, CLSCTX_LOCAL_SERVER,

IID_IVoiceCmd, (LPVOID *) &gpIVoiceCommand) != S_OK)

goto fail;

// Retrieve the address of the voice-command object's IVCmdDialogs

// interface. The application uses this interface to direct the

// speech-recognition engine to display its configuration dialog boxes.

hRes = gpIVoiceCommand-QueryInterface(IID_IVCmdDialogs,

(LPVOID FAR *) &gpIVCmdDialogs);

if (hRes)

goto fail;

// Register the application with the voice-command object.

hRes = gpIVoiceCommand->Register(

"", // use the default site (computer microphone)

&gVCmdNotifySink, // address of application's notification interface

IID_IVCmdNotifySink, // GUID of the notification interface

VCMDRF_ALLMESSAGES, // send all notifications to the interface

NULL); // do not change the site settings

if (hRes)

goto fail;

// Use the voice command's IVCmdAttributes interface to ensure that

// speech recognition is awake and enabled for the whole system.

hRes = gpIVoiceCommand-QueryInterface(IID_IVCmdAttributes,

(LPVOID FAR *) &pIVCmdAttributes);

if (pIVCmdAttributes) {

pIVCmdAttributes-EnabledSet(TRUE);

pIVCmdAttributes-AwakeStateSet(TRUE);

pIVCmdAttributes-Release();

};

// Create a voice-menu object.

lstrcpy (VcmdName.szApplication, "My Demo Application");

lstrcpy (VcmdName.szState, "Main");

Language.LanguageID = LANG_ENGLISH;

lstrcpy (Language.szDialect, "US English");

hRes = gpIVoiceCommand->MenuCreate(

&VcmdName, // application name and state

&Language, // language and dialect

VCMDMC_CREATE_TEMP, // temporary menu (not stored in database)

&gpIVCmdMenu // receives address of voice-menu object

);

if (hRes)

goto fail;

return TRUE;

// If the BeginOLE function fails, release the IVoiceCmd, IVCmdDialogs,

// and IVCmdMenu interfaces and set the interface pointers to NULL.

fail:

if (gpIVoiceCommand)

gpIVoiceCommand->Release();

if (gpIVCmdDialogs)

gpIVCmdDialogs->Release();

if (gpIVCmdMenu)

gpIVCmdMenu->Release();

gpIVoiceCommand = NULL;

gpIVCmdDialogs = NULL;

gpIVCmdMenu = NULL;

return FALSE;

}