IAgentCommand

[Microsoft Agent is deprecated as of Windows 7, and may be unavailable in subsequent versions of Windows.]

A Command object is an item in a Commands collection. The server provides the user access to your commands your client application becomes input active. To retrieve a Command, call IAgentCommands::GetCommand.

IAgentCommand defines an interface that allows applications to set and query properties for Command objects that can appear in a character's pop-up menu and in the Voice Commands Window. These functions are also available from IAgentCommandEx. A Command object is an item in a Commands collection. The server provides the user access to your commands when your client application becomes input active.

A Command may appear in either or both the character's pop-up menu and the Voice Commands Window. To appear in the pop-up menu, it must have a Caption and have the Visible property set to True. The Visible property for its Commands collection object must also be set to True for the command to appear in the pop-up menu when your client application is input-active. To appear in the Voice Commands Window, a Command must have its VoiceCaption and Voice properties set. (For backward compatibility, if there is no VoiceCaption, the Caption setting is used.)

A character's pop-up menu entries do not change while the menu is displayed. If you add or remove Commands or change their properties while the character's popup menu is displayed, the menu displays those changes when redisplayed. However, the Voice Commands Window does display changes as you make them.

The following table summarizes how the properties of a command affect its presentation.

Caption Property	Voice-Caption Property	Voice Property	Visible Property	Appears in Character's Pop-up Menu	Appears in Voice Commands Window
Yes	Yes	Yes	True	Yes, using Caption	Yes, using VoiceCaption
Yes	Yes	No¹	True	Yes, using Caption	No
Yes	Yes	Yes	False	No	Yes, using VoiceCaption
Yes	Yes	No¹	False	No	No
No¹	Yes	Yes	True	No	Yes, using VoiceCaption
No¹	Yes	Yes	False	No	Yes, using VoiceCaption
No¹	Yes	No¹	True	No	No
No¹	Yes	No¹	False	No	No
Yes	No¹	Yes	True	Yes, using Caption	Yes, using Caption
Yes	No¹	No¹	True	Yes	No
Yes	No¹	Yes	False	No	Yes, using Caption
Yes	No¹	No¹	False	No	No
No¹	No¹	Yes	True	No	No²
No¹	No¹	Yes	False	No	No²
No¹	No¹	No¹	True	No	No
No¹	No¹	No¹	False	No	No

 

¹If the property setting is null. In some programming languages, an empty string may not be interpreted as the same as a null string.

²The command is still voice-accessible.

Generally, if you define a Command with a Voice setting, you also define Caption and Voice settings for its associated Commands collection. If the Commands collection for a set of commands has no Voice or no Caption setting and is currently input-active, but the Commands have Caption and Voice settings, the Commands appear in the Voice Commands Window tree view under "(undefined command)" when your client application becomes input-active.

When the server receives input that matches one of the Command objects you defined for your Commands collection, it sends a IAgentNotifySink::Command event, and passes back the ID of the command as an attribute of the IAgentUserInput object. You can then use conditional statements to match and process the command.

Methods in Vtable Order

IAgentCommand Methods	Description
SetCaption	Sets the value for the Caption for a Command object.
GetCaption	Returns the value of the Caption property of a Command object.
SetVoice	Sets the value for the Voice text for a Command object.
GetVoice	Returns the value of the Voice property of a Command object.
SetEnabled	Sets the value of the Enabled property for a Command object.
GetEnabled	Returns the value of the Enabled property of a Command object.
SetVisible	Sets the value of the Visible property for a Command object.
GetVisible	Returns the value of the Visible property of a Command object.
SetConfidenceThreshold	Sets the value of the Confidence property for a Command object.
GetConfidenceThreshold	Returns the value of the Confidence property of a Command object.
SetConfidenceText	Sets the value of the ConfidenceText property for a Command object.
getConfidenceText	Returns the value of the ConfidenceText property of a Command object.
getID	Returns the ID of a Command object.