IAgentCommand

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 Commands Window. 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 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 Commands Window, a Command must have its Caption and Voice properties set.

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 Commands Window does display changes as you make them.

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

^*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 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::GetCaption

HRESULT GetCaption(
   BSTR * pbszCaption  // address of Caption for Command
);

Retrieves the Caption for a Command.

• Returns S_OK to indicate the operation was successful.

pbszCaption

The address of a BSTR that receives the value of the Caption text displayed for a Command.

See also IAgentCommand::SetCaption, IAgentCommand::SetEnabled, IAgentCommand::SetVisible, IAgentCommand::SetVoice, IAgentCommands::Add, IAgentCommands::Insert

IAgentCommand::GetConfidenceText

HRESULT GetConfidenceText(
   BSTR * pbszTipText  // address of ConfidenceText setting for Command 
);

Retrieves the Listening Tip text previously set for a Command.

• Returns S_OK to indicate the operation was successful.

pbszTipText

The address of a BSTR that receives the value of the Listening Tip text for a Command.

See also IAgentCommand::SetConfidenceThreshold, IAgentCommand::GetConfidenceThreshold, IAgentCommand::SetConfidenceText, IAgentUserInput::GetItemConfidence

IAgentCommand::GetConfidenceThreshold

HRESULT GetConfidenceThreshold(
long * plConfidenceThreshold  // address of ConfidenceThreshold 
);                            // setting for Command

Retrieves the value of the ConfidenceThreshold property for a Command.

• Returns S_OK to indicate the operation was successful.

plConfidenceThreshold

The address of a variable that receives the value of the ConfidenceThreshold property for a Command.

See also IAgentCommand::SetConfidenceThreshold, IAgentCommand::SetConfidenceText, IAgentUserInput::GetItemConfidence

IAgentCommand::GetEnabled

HRESULT GetEnabled(
   long * pbEnabled  // address of Enabled setting for Command
);

Retrieves the value of the Enabled property for a Command.

• Returns S_OK to indicate the operation was successful.

pbEnabled

The address of a variable that receives TRUE if the Command is enabled, or FALSE if it is disabled. A disabled Command cannot be selected.

See also IAgentCommand::SetCaption, IAgent::SetVisible, IAgentCommand::SetVoice, IAgentCommands::Add, IAgentCommands::Insert

IAgentCommand::GetID

HRESULT GetID(
   long * pdwID  // address of ID for Command
);

Retrieves the ID for a Command.

• Returns S_OK to indicate the operation was successful.

pdwID

The address of a variable that receives the ID of a Command.

See also IAgentCommands::Add, IAgentCommands::Insert, IAgentCommands::Remove

IAgentCommand::GetVisible

HRESULT GetVisible(
   long * pbVisible  // address of Visible setting for Command
);

Retrieves the value of the Visible property for a Command.

• Returns S_OK to indicate the operation was successful.

pbVisible

The address of a variable that receives the Visible property for a Command.

See also IAgentCommand::SetVisible, IAgent::SetCaption, IAgentCommands::Add, IAgentCommands::Insert

IAgentCommand::GetVoice

HRESULT GetVoice(
   BSTR * pbszVoice  // address of Voice setting for Command
);

Retrieves the value of the Voice text property for a Command.

• Returns S_OK to indicate the operation was successful.

pbszVoice

The address of a BSTR that receives the Voice text property for a Command.

A Command with its Voice property set and its Enabled property set to TRUE will be voice-accessible. If its Caption property is also set it appears in the Commands Window. If its Visible property is set to TRUE, it appears in the character's pop-up menu.

See also IAgentCommand::SetVoice, IAgentCommands::Add, IAgentCommands::Insert

IAgentCommand::SetCaption

HRESULT SetCaption(
   BSTR bszCaption  // Caption setting for Command
);

Sets the Caption text displayed for a Command.

• Returns S_OK to indicate the operation was successful.

bszCaption

A BSTR that specifies the text for the Caption property for a Command.

A Command with its Caption property set and its Visible property set to TRUE appears in the character's pop-up menu. If its Voice property is also set, it appears in the Commands Window. To make it accessible, you must also set its Enabled property to TRUE.

See also IAgentCommand::GetCaption, IAgentCommand::SetEnabled, IAgentCommand::SetVisible, IAgentCommand::SetVoice, IAgentCommands::Add, IAgentCommands::Insert

IAgentCommand::SetConfidenceThreshold

HRESULT SetConfidenceThreshold(
   long lConfidence  // Confidence setting for Command
);

Sets the value of the Confidence property for a Command.

• Returns S_OK to indicate the operation was successful.

lConfidence

The value for the Confidence property of a Command.

If the confidence value returned of the best match returned in the Command event does not exceed the value set for the ConfidenceThreshold property, the text supplied in SetConfidenceText is displayed in the Listening Tip.

See also IAgentCommand::GetConfidenceThreshold, IAgentCommand::SetConfidenceText, IAgentUserInput::GetItemConfidence

IAgentCommand::SetConfidenceText

HRESULT SetConfidenceText(
   BSTR bszTipText  // ConfidenceText setting for Command 
);

Sets the value of the Listening Tip text for a Command.

• Returns S_OK to indicate the operation was successful.

bszTipText

A BSTR that specifies the text for the ConfidenceText property of a Command.

If the confidence value returned of the best match returned in the Command event does not exceed the value set for the ConfidenceThreshold property, the text supplied in bszTipText is displayed in the Listening Tip.

See also IAgentCommand::SetConfidenceThreshold, IAgentCommand::GetConfidenceThreshold, IAgentCommand::GetConfidenceText, IAgentUserInput::GetItemConfidence

IAgentCommand::SetEnabled

HRESULT SetEnabled(
   long bEnabled  // Enabled setting for Command
);

Sets the Enabled property for a Command.

• Returns S_OK to indicate the operation was successful.

bEnabled

A Boolean value that sets the value of the Enabled setting of a Command. TRUE enables the Command; FALSE disables it. A disabled Command cannot be selected.

A Command must have its Enabled property set to TRUE to be selectable. It also must have its Caption property set and its Visible property set to TRUE to appear in the character's pop-up menu. To make the Command appear in the Commands Window, you must set its Voice property.

See also IAgentCommand::GetCaption, IAgentCommand::SetVoice, IAgentCommands::Add, IAgentCommands::Insert

IAgentCommand::SetVisible

HRESULT SetVisible(
   long bVisible  // Visible setting for Command
);

Sets the value of the Visible property for a Command.

• Returns S_OK to indicate the operation was successful.

bVisible

A Boolean value that determines the Visible property of a Command. TRUE shows the Command; FALSE hides it.

A Command must have its Visible property set to TRUE and its Caption property set to appear in the character's pop-up menu.

See also IAgentCommand::GetVisible, IAgent::SetCaption, IAgentCommands::Add, IAgentCommands::Insert

IAgentCommand::SetVoice

HRESULT SetVoice(
   BSTR bszVoice  // voice text setting for Command
);

Sets the Voice property for a Command.

• Returns S_OK to indicate the operation was successful.

bszVoice

A BSTR that specifies the text for the Voice property of a Command.

A Command must have its Voice property and Enabled property set to be voice-accessible. It also must have its Caption property set to appear in the Commands Window.

The BSTR expression you supply can include square bracket characters ([ ]) to indicate optional words and vertical bar characters (|) to indicate alternative strings. Alternates must be enclosed in parentheses. For example, "(hello [there] | hi)" tells the speech engine to accept "hello," "hello there," or "hi" for the command. Remember to include appropriate spaces between the text that's in brackets or parentheses and the text that's not in brackets or parentheses.

You can also use an ellipsis (…) to support word spotting, that is, telling the speech recognition engine to ignore words spoken in this position in the phrase (sometimes called garbage words). Therefore, the speech engine recognizes only specific words in the string regardless of when spoken with adjacent words or phrases. For example, if you set this property to "…check mail…" the speech recognition engine will match phrases like "please check mail" or "check mail please" to this command. Ellipses can be used anywhere within a string. However, be careful using this technique, because voice settings with ellipses may increase the potential of unwanted matches.

When defining the words and grammar for your command, always make sure that you include at least one word that is required; that is, avoid supplying only optional words. In addition, make sure that the word includes only pronounceable words and letters. For numbers, it is better to spell out the word rather than using the numeric representation. Also, omit any punctuation or symbols. For example, instead of "the #1 $10 pizza!", use "the number one ten dollar pizza". Including non-pronounceable characters or symbols for one command may cause the speech engine to fail to compile the grammar for all your commands. Finally, make your voice parameter as distinct as reasonably possible from other voice commands you define. The greater the similarity between the voice grammar for commands, the more likely the speech engine will make a recognition error. You can also use the confidence scores to better distinguish between two commands that may have similar or similar-sounding voice grammar.

The operation of this property depends on the state of Microsoft Agent server's speech recognition state. For example, if speech recognition is disabled or not installed, this function has no immediate effect. If speech recognition is enabled during a session, however, the command will become accessible when its client application is input-active.

See also IAgentCommand::GetVoice, IAgentCommand::SetCaption, IAgentCommand::SetEnabled, IAgentCommands::Add, IAgentCommands::Insert