IVoiceCmd::MenuCreate
This method creates a voice menu object to represent a new or existing voice menu for an application.
Syntax
HRESULT MenuCreate( PVCMDNAME pName, PLANGUAGE pLanguage, DWORD dwFlags, PIVCMDMENU *ppIVCmdMenu);
Parameters
- pName
- [in] Pointer to a VCMDNAME structure that identifies the menu to create. The VCMDNAME structure contains an application name, such as “Radio,” and a state name, such as “main form.”
- pLanguage
- [in] Pointer to 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] Specifies how to create the menu. It is one of the following flags:
- VCMDMC_CREATE_ALWAYS
- Creates an empty menu with the specified name. If a menu by that name already exists in the voice menu database, it is erased. For Microsoft Windows CE for the Auto PC, the voice menu is removed from the database when the menu is released.
- VCMDMC_CREATE_NEW
- Creates an empty menu with the specified name. If a menu by that name already exists in the voice menu database, the method 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 specified name. If a menu by that name already exists in the voice menu database, the method 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 specified name. If the menu does not exist, the method creates a new, empty menu. The new menu is stored in the database when the menu object is released.
- ppIVCmdMenu
- [out] Pointer to an IVCmdMenu interface for the newly created voice menu object. The application uses the pointer to this interface to call IVCmdMenu methods on the voice menu object. If an error occurs, this parameter receives NULL.
Return Values
- NOERROR
- The method successfully created a voice menu object.
- E_INVALIDARG
- The argument is invalid.
- VCMDERR_CANTCREATESTORAGE
- Space cannot be created in the database for the menu.
- VCMDERR_MENUDOESNOTEXIST
- The requested menu does not exist in the database.
- VCMDERR_MENUEXIST
- The requested new or temporary menu already exists in the database.
- VCMDERR_OUTOFDISK
- No disk space is left to write information.
- VCMDERR_OUTOFMEM
- There is no more memory.
- VCMDERR_VALUEOUTOFRANGE
- The value is out of range.
Remarks
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 does not need to 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 method 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.
For the Auto PC, developers should use IApcSpeech::CreateVMenu to create a voice menu instead.