IAPCSpeech::CreateVMenu

This method creates a voice menu.

Syntax

HRESULT IAPCSpeech::CreateVMenu( PIVOICECMDW pVCmd, VCMDNAME lpName, HINSTANCE hInst, DWORD dwCmdCnt, LPVOID pCmdTable, DWORD dwFlags, PIVCMDMENUW* ppVMenu );

Parameters

pVCmd

Pointer to a voice command. This parameter should be NULL unless the application creates the voice command.

lpName

Long pointer to a unique VCMDNAME data type for each Apcspch object.

hInst

Handle to the application or dynamic link library instance.

dwCmdCnt

DWORD that indicates the total number of items in the array pointed to by pCmdTable.

pCmdTable

Pointer to an array table of resource string identifiers.

dwFlags

Bitmask of flags. Set to 0 or to APCSPCH_VM_USEEXISTING.

When APCSPCH_VM_USEEXISTING is set and the application finds that the menu already exists, it uses the menu stored in the storage file. You can still pass in the string table pointer, but it is ignored if the APCSPCH_VM_USEEXISTING flag is set and there are commands in the menu.

If a voice menu can be loaded or activated by two processes at the same time, the menu has to be created using the APCSPCH_VM_USEEXISTING flag.

If the menu is created using APCSPCH_VM_USEEXISTING flag, the calls to AddVMenuCommand must pass APCSPCH_VM_USEEXISTING.

ppVMenu

Pointer to a pointer to a voice menu.

Return Values

An appropriate HRESULT value is returned.

Remarks

The second parameter of the CreateVMenu method is the VCMDNAME structure, which contains both the application name and menu name. The application has to pass both the application name—essentially, a context name—and menu name when creating a voice menu. For example, when the edit control creates a menu, it can use the application name “EditCtrl,” and an address book DLL can use the application name “AddrBook.”

When a control or shared DLL wants to create a menu that is shared across all the instances, it should use the flag APCSPCH_VM_USEEXISTING and pass in the same application name and menu name in every instance of the control. However, if a control has a different voice menu in different instances, it should use a unique menu name. If not, the CreateVMenu fails and returns a VCMDERR_MENUEXIST error value.

The caller is responsible for releasing the menu object by calling Release. To create a default menu, pVCmd should be NULL. If the application has another voice command, it can pass it to pVCmd.

The application should call the Activate and Deactivate methods to activate or deactivate the application grammar.