IAgentUserInput

When a Command event occurs, the Microsoft Agent server returns information through the UserInput object. IAgentUserInput defines an interface that allows applications to query these values.

Methods in Vtable Order

IAgentUserInput Methods	Description
GetCount	Returns the number of command alternatives returned in a Command event.
GetItemId	Returns the ID for a specific Command alternative.
GetItemConfidence	Returns the value of the Confidence property for a specific Command alternative.
GetItemText	Returns the value of Voice text for a specific Command alternative.
GetAllItemData	Returns the data for all Command alternatives.

IAgentUserInput::GetAllItemData

HRESULT GetAllItemData(
   VARIANT * pdwItemIndices,  // address of variable for alternative IDs
   VARIANT * plConfidences,   // address of variable for confidence scores
   VARIANT * pbszText         // address of variable for voice text
);

Retrieves the data for all Command alternatives passed to an IAgentNotifySink::Command callback.

Returns S_OK to indicate the operation was successful.

pdwItemIndices

Address of a variable that receives the IDs of Commands passed to the IAgentNotifySink::Command callback.

plConfidences

Address of a variable that receives the confidence scores for Command alternatives passed to the IAgentNotifySink::Command callback.

pbszText

Address of a variable that receives the voice text for Command alternatives passed to the IAgentNotifySink::Command callback.

If voice input was not the source for the Command, for example, if the user selected the command from the character's pop-up menu, the Microsoft Agent server returns the ID of the Command selected, with a confidence score of 100 and voice text as NULL. The other alternatives return as NULL with confidence scores of zero (0) and voice text as NULL.

See also IAgentUserInput::GetItemConfidence, IAgentUserInput::GetItemText, IAgentUserInput::GetItemID

IAgentUserInput::GetCount

HRESULT GetCount(
   long * pdwCount  // address of a variable for number of alternatives 
);

Retrieves the number of Command alternatives passed to an IAgentNotifySink::Command callback.

Returns S_OK to indicate the operation was successful.

pdwCount

Address of a variable that receives the count of Commands alternatives identified by the server.

If voice input was not the source for the command, for example, if the user selected the command from the character's pop-up menu, GetCount returns 1. If GetCount returns zero (0), the speech recognition engine detected spoken input but determined that there was no matching command.

IAgentUserInput::GetItemConfidence

HRESULT GetItemConfidence(
   long dwItemIndex,    // index of Command alternative
   long * plConfidence  // address of confidence value for Command 
);

Retrieves the confidence value for a Command passed to an IAgentNotifySink::Command callback.

Returns S_OK to indicate the operation was successful.

dwItemIndex

The index of a Command alternative passed to the IAgentNotifySink::Command callback.

plConfidence

Address of a variable that receives the confidence score for a Command alternative passed to the IAgentNotifySink::Command callback.

If voice input was not the source for the command, for example, if the user selected the command from the character's pop-up menu, the Microsoft Agent server returns the confidence value of the best match as 100 and the confidence values for all other alternatives as zero (0).

See also IAgentUserInput::GetItemID, IAgentUserInput::GetAllItemData, IAgentUserInput::GetItemText

IAgentUserInput::GetItemID

HRESULT GetItemID(
   long dwItemIndex,    // index of Command alternative
   long * pdwCommandID  // address of a variable for number of alternatives 
);

Retrieves the identifier of a Command alternative passed to an IAgentNotifySink::Command callback.

Returns S_OK to indicate the operation was successful.

dwItemIndex

The index of the Command alternative passed to the IAgentNotifySink::Command callback.

pdwCommandID

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

If voice input triggers the IAgentNotifySink::Command callback, the server returns the IDs for any matching Commands defined by your application.

See also IAgentUserInput::GetItemConfidence, IAgentUserInput::GetItemText, IAgentUserInput::GetAllItemData

IAgentUserInput::GetItemText

HRESULT GetItemText(
   Long dwItemIndex,  // index of Command alternative
   BSTR * pbszText    // address of voice text for Command 
);

Retrieves the voice text for a Command alternative passed to the IAgentNotifySink::Command callback.

Returns S_OK to indicate the operation was successful.

dwItemIndex

The index of a Command alternative passed to the IAgentNotifySink::Command callback.

pbszText

Address of a BSTR that receives the value of the voice text for the Command.

If voice input was not the source for the command, for example, if the user selected the command from the character's pop-up menu, the server returns NULL for the Command's voice text.

See also IAgentUserInput::GetItemConfidence, IAgentUserInput::GetItemID, IAgentUserInput::GetAllItemData