IVoiceCmd::MenuEnum
This method creates a voice menu enumerator to enumerate menus in the voice menu database.
Syntax
HRESULT MenuEnum( DWORD dwFlags, PTSTR pszApplicationFilter, PTSTR pszStateFilter, PIVCMDENUM *ppiVCmdEnum);
Parameters
- dwFlags
- [in] Specifies whether to enumerate active menus or open menus, which have voice menu objects, but may or may not be active. It is a combination of some of the following flags:
- VCMDEF_ACTIVE
- Enumerates only active menus.
- VCMDEF_DATABASE
- Enumerates all menus in the voice menu 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 VCMDEF_ACTIVE and VCMDEF_SELECTED are specified, the method returns an error. VCMDEF_TEMPORARY and VCMDEF_PERMANENT are ignored if neither VCMDEF_ACTIVE nor VCMDEF_SELECTED are specified. In other words, these flags 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] Pointer to the null-terminated string that contains the name of the application whose menus are enumerated. This name is the same as that in the szApplication member of the VCMDNAME structure passed to the IVoiceCmd::MenuCreate method. If this parameter is NULL, menus for all applications, except those eliminated by dwFlags and pszStateFilter, are enumerated.
- pszStateFilter
- [in] Pointer to a null-terminated string that contains the name of the state whose menus are enumerated. This state is the same as that in the szState member of the VCMDNAME structure passed to MenuCreate. If this parameter is NULL, menus for all applications, except those eliminated by dwFlags and pszApplicationFilter, are enumerated.
- ppiVCmdEnum
- [out] Pointer to 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.
Return Values
- NOERROR
- The method successfully created a voice menu enumerator.
- E_INVALIDARG
- The argument is invalid.
- VCMDERR_INVALIDMODE
- No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
- VCMDERR_MENUDOESNOTEXIST
- The requested menu does not exist in the database.
- VCMDERR_OUTOFMEM
- There is no more memory.
- VCMDERR_VALUEOUTOFRANGE
- The value is out of range.
Remarks
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.