IAgentCommands

The Microsoft Agent server maintains a list of commands that are currently available to the user. This list includes commands that the server defines for general interaction, such as Hide and Microsoft Agent Properties, the list of available (but non-input-active) clients, and the commands defined by the current active client. The first two sets of commands are global commands; that is, they are available at any time, regardless of the input-active client. Client-defined commands are available only when that client is input-active.

Retrieve an IAgentCommands interface by querying the IAgentCharacter interface for IAgentCommands. Each Microsoft Agent client application can define a collection of commands called a Commands collection. To add a Command to the collection, use the Add or Insert method. Although you can specify a Command's properties using IAgentCommand methods, for optimum code performance, specify all of a Command's properties in the IAgentCommands::Add or IAgentCommands::Insert methods when initially setting the properties for a new Command. You can use the IAgentCommand methods to query or change the property settings.

For each Command in the Commands collection, you can determine whether the command appears on the character's pop-up menu, in the Commands Window, in both, or in neither. For example, if you want a command to appear on the pop-up menu for the character, set the command's Caption and Visible properties. To display the command in the Commands Window, set the command's Caption and Voice properties.

A user can access the individual commands in your Commands collection only when your client application is input-active. Therefore, you will typically want to set the Caption and Voice properties for the Commands collection object as well as for the commands in the collection, because this places an entry for your Commands collection on a character's pop-up menu and in the Commands Window. When the user switches to your client by choosing its entry, the server automatically makes your client input-active and makes the Commands in its collection available. This enables the server to present and accept only the Commands that apply to the current input-active client's context. It also serves to avoid Command-name collisions between clients.

When a character's pop-up menu is displayed, changes to the properties of a Commands collection or the commands in its collection do not appear until the user redisplays the menu. However, when open, the Commands Window does display changes as they happen.

IAgentCommands defines an interface that allows applications to add, remove, set, and query properties for a Commands collection. A Commands collection can appear as a command in both the pop-up menu and the Commands Window for a character. To make the Commands collection appear, you must set its Caption property. The following table summarizes how the properties of a Commands collection affect its presentation.

^*The command is still voice-accessible. If the client is input-active and has Commands in its collection, "(command undefined)" appears in the Commands Window.

Methods in Vtable Order

IAgentCommands::Add

HRESULT Add(
   BSTR bszCaption,  // Caption setting for Command
   BSTR bszVoice,    // Voice setting for Command
   long bEnabled,    // Enabled setting for Command
   long bVisible,    // Visible setting for Command
   long * pdwID      // address for variable for ID
);

Adds a Command to a Commands collection.

• Returns S_OK to indicate the operation was successful.

bszCaption

A BSTR that specifies the value of the Caption text displayed for a Command in a Commands collection.

bszVoice

A BSTR that specifies the value of the Voice text setting for a Command in a Commands collection.

bEnabled

A Boolean expression that specifies the Enabled setting for a Command in a Commands collection. If the parameter is TRUE, the Command is enabled and can be selected; if FALSE, the Command is disabled.

bVisible

A Boolean expression that specifies the Visible setting for a Command in a Commands collection. If the parameter is TRUE, the Command will be visible in the character's pop-up menu (if the Caption property is also set).

pdwID

Address of a variable that receives the ID for the added Command.

See also IAgentCommand::SetCaption, IAgentCommand::SetEnabled, IAgentCommand::SetVisible, IAgentCommand::SetVoice, IAgentCommands::Insert, IAgentCommands::Remove, IAgentCommands::RemoveAll

IAgentCommands::GetCaption

HRESULT GetCaption(
   BSTR * pbszCaption  // address of Caption text for Commands collection
);

Retrieves the Caption for a Commands collection.

• Returns S_OK to indicate the operation was successful.

pbszCaption

The address of a BSTR that receives the value of the Caption text setting displayed for a Commands collection.

See also IAgentCommands::SetCaption, IAgentCommands::GetVisible, IAgentCommands::GetVoice

IAgentCommands::GetCommand

HRESULT GetCommand(
   long dwCommandID,         // Command ID
   IUnknown ** ppunkCommand  // address of IUnknown interface
);                    

Retrieves a Command object from the Commands collection.

• Returns S_OK to indicate the operation was successful.

dwCommandID

The ID of a Command object in the Commands collection.

IUnknown

The address of the IUnknown interface for the Command object.

See also IAgentCommand

IAgentCommands::GetCount

HRESULT GetCount(
   long * pdwCount  // address of count of commands
);                    

Retrieves the number of Command objects in a Commands collection.

• Returns S_OK to indicate the operation was successful.

pdwCount

Address of a variable that receives the number of Commands in a Commands collection.

pdwCount includes only the number of Commands you define in your Commands collection. Server or other client entries are not included.

IAgentCommands::GetVisible

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

Retrieves the value of the Visible property for a Commands collection.

• Returns S_OK to indicate the operation was successful.

pbVisible

The address of a variable that receives the value of the Visible property for a Commands collection.

See also IAgentCommands::SetVisible, IAgentCommands::SetCaption

IAgentCommands::GetVoice

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

Retrieves the value of the Voice property for a Commands collection.

• Returns S_OK to indicate the operation was successful.

pbszVoice

The address of a BSTR that receives the value of the Voice text setting for a Commands collection.

See also IAgentCommands::SetVoice, IAgentCommands::GetCaption, IAgentCommands::GetVisible

IAgentCommands::Insert

HRESULT Insert(
   BSTR bszCaption,  // Caption setting for Command
   BSTR bszVoice,    // Voice setting for Command
   long bEnabled,    // Enabled setting for Command
   long bVisible,    // Visible setting for Command
   long dwRefID,     // reference Command for insertion
   long dBefore,     // insertion position flag
   long * pdwID      // address for variable for Command ID
);

Inserts a Command object in a Commands collection.

• Returns S_OK to indicate the operation was successful.

bszCaption

A BSTR that specifies the value of the Caption text displayed for the Command.

bszVoice

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

bEnabled

A Boolean expression that specifies the Enabled setting for a Command. If the parameter is TRUE, the Command is enabled and can be selected; if FALSE, the Command is disabled.

bVisible

A Boolean expression that specifies the Visible setting for a Command. If the parameter is TRUE, the Command will be visible in the character's pop-up menu (if the Caption property is also set).

dwRefID

The ID of a Command used as a reference for the relative insertion of the new Command.

dBefore

A Boolean expression that specifies where to place the Command. If this parameter is TRUE, the new Command is inserted before the referenced Command; if FALSE, the new Command is placed after the referenced Command.

pdwID

Address of a variable that receives the ID for the inserted Command.

See also IAgentCommand::Add, IAgentCommands::Remove, IAgentCommands::RemoveAll

IAgentCommands::Remove

HRESULT Remove(
   long dwID  // Command ID
);

Removes the specified Command from a Commands collection.

• Returns S_OK to indicate the operation was successful.

dwID

The ID of a Command to remove from the Commands collection.

Removing a Command from a Commands collection also removes it from the pop-up menu and the Commands Window when your application is input-active.

See also IAgentCommands::Add, IAgentCommands::Insert, IAgentCommands::RemoveAll

IAgentCommands::RemoveAll

HRESULT Remove();

Removes all Commands from a Commands collection.

• Returns S_OK to indicate the operation was successful.

Removing all Commands from a Commands collection also removes them from the pop-up menu and the Commands Window when your application is input-active. RemoveAll does not remove server or other client's entries.

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

IAgentCommands::SetCaption

HRESULT SetCaption(
   BSTR bszCaption  // Caption setting for Commands collection
);

Sets the Caption text displayed for a Commands collection.

• Returns S_OK to indicate the operation was successful.

bszCaption

A BSTR that specifies the value for the Caption property for a Commands collection.

A Commands collection 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. If you define commands for a Commands collection that have their Caption, Enabled, and Voice properties set, you typically also define Caption and Voice settings for the associated Commands collection. If the Commands collection has no Voice or no Caption setting and is currently input-active, but the Commands in its collection have Caption and Voice settings, the Commands appear in the Commands Window tree view under "(undefined command)" when your client application becomes input-active.

See also IAgentCommands::GetCaption, IAgentCommands::SetVisible, IAgentCommands::SetVoice

IAgentCommands::SetVisible

HRESULT SetVisible(
   long bVisible  // the Visible setting for Commands collection
);

Sets the value of the Visible property for a Commands collection.

• Returns S_OK to indicate the operation was successful.

bVisible

A Boolean value that determines the Visible property of a Commands collection. TRUE sets the Commands collection's Caption to be visible when the character's pop-up menu is displayed; FALSE does not display it.

A Commands collection must have its Caption property set and its Visible property set to TRUE to appear on the character's pop-up menu. The Visible property must also be set to TRUE for commands in the collection to appear when your client application is input-active.

See also IAgentCommands::GetVisible, IAgent::SetCaption

IAgentCommands::SetVoice

HRESULT SetVoice(
   BSTR bszVoice  // the Voice setting for Command collection
);

Sets the Voice text property for a Command.

• Returns S_OK to indicate the operation was successful.

bszVoice

A BSTR that specifies the value for the Voice text property of a Commands collection.

A Commands collection must have its Voice text property set to be voice-accessible. It also must have its Caption property set to appear in the Commands Window and its Visible property set to TRUE to appear on the character's pop-up menu.

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 words you include in brackets or parentheses as well as other text. 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). When you use ellipses, 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 as 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 IAgentCommands::GetVoice, IAgentCommands::SetCaption, IAgentCommands::SetVisible