IVCmdMenu::ListSet

This method sets the phrases in a list for a voice command.

Syntax

HRESULT ListSet( PTSTR pszList, DWORD dwListNum, SDATA dList);

Parameters

pszList

[in] Pointer to the null-terminated string contains 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] Specifies the 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.

Return Values

NOERROR

The method successfully set the phrases in the list.

E_INVALIDARG

The argument is invalid.

VCMDERR_INVALIDCHAR

There is an invalid character in the voice menu.

VCMDERR_INVALIDLIST

An invalid list was passed.

VCMDERR_OUTOFMEM

There is no more memory.

Remarks

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—for example, “Send mail to <name>.”

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 method and take steps to store the result.

ListSet is much faster than the IVCmdMenu interface’s Add, Remove, or Set methods 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.