HRESULT ListSet(PTSTR pszList, DWORD dwListNum, SDATA dList);
Sets the phrases in a list for a voice command. The user can speak any phrase in the list in place of the list name in the command string.
A command that uses a list must have the list name in brackets. Example:
"Send mail to <name>"
· Returns NOERROR if successful, or one of these error values:
E_INVALIDARG
VCMDERR_INVALIDCHAR
VCMDERR_INVALIDLIST
VCMDERR_OUTOFMEM
pszList
[in] Address of the name of the list to set, such as "name" or "weekday." The list name must appear in the command string for at least one command on the menu. The command string is specified in the dwCommand member of the VCMDCOMMAND structure that defines the command.
dwListNum
[in] Number of phrases in the list.
dList
[in] SDATA structure that contains a pointer to a data buffer and the size of the buffer. The data buffer contains a sequential list of null-terminated strings, one for each phrase in the list.
Calling ListSet establishes a list of phrases that can be spoken in a voice command, such as "Send mail to name." Typically, the list contains information that changes dynamically at run time, such as the ten people to whom the user most recently sent electronic mail. For best results, a list should have fewer than 20 entries. Having more than 20 entries in a list can reduce the accuracy of recognition.
The list persists until the voice-menu object is released. List entries are not automatically saved to disk. To preserve the list, call the IVCmdMenu::ListGet member function and take steps to store the result.
ListSet is much faster than the IVCmdMenu interface's Add, Remove, or Set member functions because list entries are substituted when a command is recognized and the menu is not recompiled. This means that ListSet can be called on an active menu without affecting performance.