HRESULT MenuCreate(PVCMDNAME pName, PLANGUAGE pLanguage, DWORD dwFlags,
PIVCMDMENU *ppIVCmdMenu);
Creates a voice-menu object to represent a new or existing voice menu for an application.
· Returns NOERROR if successful, or one of these error values:
E_INVALIDARG
VCMDERR_CANTCREATESTORAGE
VCMDERR_MENUDOESNOTEXIST
VCMDERR_MENUEXIST
VCMDERR_OUTOFDISK
VCMDERR_OUTOFMEM
VCMDERR_VALUEOUTOFRANGE
pName
[in] Address of a VCMDNAME structure that identifies the menu to create. The VCMDNAME structure contains an application name, such as "Excel," and a state name, such as "Main menu" or "File Open dialog box."
pLanguage
[in] Address of a LANGUAGE structure that indicates the language to use for the menu. If this parameter is NULL, the default language for the site's speech-recognition mode is used.
dwFlags
[in] Flag that indicates how to create the menu. This parameter can be one of these values:
Value | Meaning |
VCMDMC_CREATE_ALWAYS | Creates an empty menu with the given name. If a menu by that name already exists in the voice-menu database, it is erased. The new menu is stored in the database when the menu object is released. |
VCMDMC_CREATE_NEW | Creates an empty menu with the given name. If a menu by that name already exists in the voice-menu database, the function returns an error. The new menu is stored in the database when the menu object is released. |
VCMDMC_CREATE_TEMP | Creates an empty menu with the given name. If a menu by that name already exists in the voice-menu database, the function returns an error. The new menu is temporary and is discarded when the menu object is released. |
VCMDMC_OPEN_ALWAYS | Opens an existing menu with the given name. If the menu does not exist, the function creates a new, empty menu. The new menu is stored in the database when the menu object is released. |
VCMDMC_OPEN_EXISTING | Opens an existing menu. If the menu does not exist, the function returns an error. |
ppIVCmdMenu
[out] Address of an IVCmdMenu interface for the newly created voice-menu object. The application uses the pointer to this interface to call IVCmdMenu functions on the voice-menu object. If an error occurs, this parameter receives NULL.
An application can create a voice-menu object by loading an existing voice menu from the voice-menu database or creating a new voice menu. A voice menu need not be stored in the database; an application can create a temporary voice menu by setting dwFlags to the VCMDMC_CREATE_TEMP value. A temporary voice menu persists until the menu object is released.
An application can create more than one voice-menu object to represent the same menu — either one of its own menus or a menu for another application. For example, one application might do this to enumerate another application's menus.
More than one application can use the same voice-menu object. For example, Application A might call the IVoiceCmd::CmdMimic member function on a voice-menu object that represents a menu for Application B, while Application B uses the same menu object to recognize commands spoken by the user.