typedef struct { // vccmd
DWORD dwSize;
DWORD dwFlags;
DWORD dwID;
DWORD dwCommand;
DWORD dwDescription;
DWORD dwCategory;
DWORD dwCommandText;
DWORD dwAction;
DWORD dwActionSize;
BYTE abData[];
} VCMDCOMMAND, *PVCMDCOMMAND;
Provides information about a command in a voice menu.
dwSize
Size, in bytes, of the VCMDCOMMAND structure, including the amount allocated for abData. The contents of abData must be doubleword-aligned, so round dwSize up to the nearest whole doubleword.
dwFlags
Flags that indicate information about the command. This member can be a combination of these values:
Value | Meaning |
VCMDCMD_DISABLED_PERM | The command was disabled by using the IVCmdMenu::EnableItem member function so that voice commands will not recognize it. The command is not compiled into the voice menu. |
VCMDCMD_DISABLED_TEMP | The command was disabled by using the IVCmdMenu::SetItem member function. The command is still compiled into the voice menu, however, so it can be reenabled without recompilation of the menu. |
VCMDCMD_VERIFY | The application should prompt the user to verify the command before carrying it out. For example, this value should be set for a "Delete File" command. This value may be combined with either of the other values. |
VCMDCMD_CANTRENAME | (New for 3.0) This indicates that the command is automatically generated and that navigator applications (such as Microsoft Voice) shouldn't allow users to rename the command. For example: A set of commands that are generated by extracting all of the menu items in the currently running application would have this flag set since there would be little point in users renaming them. |
dwID
Command identifier. This member can be used to identify a command to modify, or it can be used for notifications.
dwCommand
Offset from the beginning of this structure to first character of the voice command string (ANSI or Unicode, depending on which character set was used in the application). For example, the voice command string might be "Open the file" and the character at the offset specified by dwCommand would be 'O'. In languages such as Japanese that have both a phonemic and symbolic character set, the dwCommand member is the offset to a phonemic string.
Within the command string, the following characters have special meaning:
Character | Meaning |
| Indicates the name of a list of words or phrases that can be spoken at this point in the command. For example, the command string "Send mail to name" contains a list called "name." To add phrases to the list, use the IVCmdMenu::ListSet member function. |
{ } | Reserved for future use. |
[ ] | Reserved for future use. |
dwDescription
Offset from the beginning of the structure to first character of a string that describes the action performed by the command.
dwCategory
Offset from the beginning of the structure to the first character of a string that indicates the category to which the command belongs.
Commands in a voice menu should be organized in different categories to help the user browse through lists of commands more easily. This is similar in concept to Windows menus, which organize commands under menu names such as "File," "Edit," "View," and so on. For best results, you should use 20 or fewer categories.
dwCommandText
Offset from the beginning of the structure to the first character of the command text, which is the string that is displayed to the user when he or she requests a list of available voice commands. If this member is NULL, an application uses the text pointed to by dwCommand, which is the voice-command string used in the application's user interface.
Most applications written for European languages will set this member to NULL because the language uses only one character set. Applications written for languages that have both a phonemic and symbolic character set, such as Japanese, will store the phonemic representation of the command in dwCommand and the symbolic representation (which is preferred by the user) in this member.
dwAction
Offset from the beginning of the structure to the first byte of a block of data that is sent to the application when the command is spoken.
Data passed with a command is not interpreted by voice commands; it is up to the application to determine whether the data is valid and to act upon it. Always check the validity of the data, because it is susceptible to being changed — accidentally or intentionally — by other applications, just as other applications can change an .INI file or registry file.
dwActionSize
Number of bytes required to store the block of data indicated by dwAction.
abData
Array of type BYTE that contains the command string, its description, its category, and additional data (if any) to pass to the application along with the command. Because all of the items in abData are doubleword-aligned, the size of abData should be a multiple of 4. All strings should be null-terminated (\0).
Because the items indicated by offsets into abData are doubleword-aligned, the offsets specified by dwCommand, dwDescription, dwCategory, dwAction, and dwActionSize should be multiples of 4.