HRESULT MenuEnum(DWORD dwFlags, PTSTR pszApplicationFilter,
PTSTR pszStateFilter, PIVCMDENUM *ppiVCmdEnum);
Creates a voice-menu enumerator that allows an application to enumerate menus in the voice-menu database.
· Returns NOERROR if successful, or one of these error values:
E_INVALIDARG
VCMDERR_INVALIDMODE
VCMDERR_OUTOFMEM
VCMDERR_VALUEOUTOFRANGE
dwFlags
[in] Indicates whether to enumerate active menus or open menus (those that have voice-menu objects, whether or not they are also active.) This parameter can be certain combinations of these values:
Value | Meaning |
VCMDEF_ACTIVE | Enumerates only active menus. |
VCMDEF_DATABASE | Enumerates all menus in the voice commands database. |
VCMDEF_PERMANENT | Enumerates only permanent menus. |
VCMDEF_SELECTED | Enumerates open menus, whether or not they are also active. |
VCMDEF_TEMPORARY | Enumerates only temporary menus. |
VCMDEF_ACTIVE and VCMDEF_SELECTED are mutually exclusive, as are VCMDEF_TEMPORARY and VCMDEF_PERMANENT. If both values are specified, the function returns an error. VCMDEF_TEMPORARY and VCMDEF_PERMANENT are ignored if neither VCMDEF_ACTIVE and VCMDEF_SELECTED are specified. In other words, they do not apply if you want to enumerate the menus in the database.
By definition, if a menu is active, it is selected.
pszApplicationFilter
[in] Address of the name of the application for which to enumerate menus. This name is the same as that in the szApplication member of the VCMDNAME structure passed to the IVoiceCmd::MenuCreate member function. If this parameter is NULL, menus for all applications, except those eliminated by dwFlags and pszStateFilter, are enumerated.
pszStateFilter
[in] Address of a string that contains the name of the state for which to enumerate menus. This is the same as in the szState member of the VCMDNAME structure passed to MenuCreate. If pszApplicationFilter is NULL, all menus except those eliminated by dwFlags and this parameter are enumerated.
ppiVCmdEnum
[out] Address of a variable that receives a pointer to an IVCmdEnum interface for the newly created voice-menu enumerator. If an error occurs, this parameter receives NULL.
An application can use a voice-menu enumerator to find and modify unknown menus or to show menu status to the user.
The voice-menu enumerator persists until all references to it are released, even if the voice-command object is released.