VCMDCOMMAND

This structure provides information about a command in a voice menu.

Syntax

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;

Members

dwSize

Specifies the size, in bytes, of the VCMDCOMMAND structure, including the amount allocated for abData. The contents of abData must be DWORD-aligned, so round dwSize up to the nearest whole DWORD.

dwFlags

Specifies the information about the command. It is a combination of the following flags:

VCMDCMD_DISABLED_PERM

The command was disabled by using the IVCmdMenu::EnableItem method so that the voice commands cannot be recognized. The command is not compiled into the voice menu.

VCMDCMD_DISABLED_TEMP

The command was disabled by using the IVCmdMenu::SetItem method. The command is still compiled into the voice menu, so it can be re-enabled without recompilation of the menu.

VCMDCMD_VERIFY

This flag is not supported in Microsoft Windows CE for the Auto PC version 1.0.

VCMDCMD_CANTRENAME

This flag is not supported in Windows CE for the Auto PC version 1.0.

dwID

Specifies the command identifier. This member can be used to identify a command to modify, or it can be used for notifications.

dwCommand

Specifies the offset from the beginning of this structure to first character of the voice command string, which is Unicode.

Within the command string, the following characters have special 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 method.

{ }

Reserved for future use.

[ ]

Reserved for future use.

dwDescription

Specifies the offset from the beginning of the structure to first character of a string that describes the action performed by the command.

dwCategory

Specifies the 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

Specifies the 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 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, store the phonemic representation of the command in dwCommand and the symbolic representation—which is preferred by the user—in dwCommandText.

dwAction

Specifies the 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

Specifies the number of bytes required to store the block of data indicated by dwAction.

abData

Array of BYTE types that contains the command string, its description, its category, and any additional data to pass to the application along with the command. Because all of the items in abData are DWORD-aligned, the size of abData should be a multiple of 4. All strings should be null-terminated.

Remarks

Because the items indicated by offsets into abData are DWORD-aligned, the offsets specified by dwCommand, dwDescription, dwCategory, dwAction, and dwActionSize should be multiples of 4.