IVCmdNotifySink::CommandRecognize

This method is sent by the engine when a spoken phrase is recognized as being from the application’s command set.

Syntax

HRESULT CommandRecognize( DWORD dwID, PVCMDNAME pvCmdName, DWORD dwFlags, DWORD dwActionSize, PVOID pAction, DWORD dwNumLists, PTSTR pszListValues, PTSTR pszCommand);

Parameters

dwID

[in] Specifies the identifier of the command that was recognized. The command identifier is stored in the dwID member of the VCMDCOMMAND structure that defines the command.

pvCmdName

[in] Void pointer to a VCMDNAME structure that contains the voice menu that has the recognized command.

dwFlags

[in] Specifies a bitmask of flags. Set to VCMDCMD_VERIFY if the application should request verification from the user, or to NULL if verification is not required. To request verification, the application should display a dialog box. An application would typically require verification for a destructive or irreversible command such as “Format disk.”

dwActionSize

[in] Specifies the size of the data in pAction.

pAction

[in] Pointer to a string that contains action data to accompany the recognized command. The action data is obtained from the VCMDCOMMAND structure for the command.

dwNumLists

[in] Specifies, in bytes, the size of the list data for the command. If a command does not contain any list fields, this parameter is zero.

pszListValues

[in] Pointer to a list of one or more null-terminated strings that correspond to the phrase from each list in the order that they occur in the command. For example, if the command is “Set the time to number AM or PM,” this parameter points to “Ten\0PM.” The last “\0” is implicit in C notation.

pszCommand

[in] Pointer to the null-terminated string for the command that was recognized.

Return Values

The return value is ignored.

Remarks

Along with the notification, the application receives the text of the phrase and the action data that was supplied by the application when it originally defined the command.

Do not use the contents of pszCommand to identify the recognized command. Instead, use the data in pAction or the identifier in dwID to determine which command was recognized.

The notification is sent to all applications that are registered on the voice command site, regardless of the what the dwFlags parameter of the IVoiceCmd::Register method was set to when the application registered to use voice commands.

If two or more global voice menus, or two or more window-specific voice menus, contain the same phrase and the engine recognizes that phrase, the engine calls CommandRecognize for one menu and IVCmdNotifySink::CommandOther for the other. The engine determines which notification to call for each menu; an application cannot determine which notification is called.