Programming the Microsoft Agent Server Interface

ActiveXŽ technology for interactive software agents

Microsoft Corporation

October 1998

Download this document in Microsoft Word (.DOC) format (zipped, 73K).

Contents
Introduction
Adding Microsoft Agent Functionality to Your Application
Loading Character and Animation Data
Creating a Notification Sink
Accessing Services Using Java
Accessing Speech Services
Reference

Introduction

Microsoft Agent provides services that enable you to program animated characters from an application. These services are implemented as an OLE Automation server. OLE Automation enables an application to control another application's object programmatically. This document assumes an understanding of the Component Object Model (COM) and OLE. For an introduction of these services, see the Programming Interface Overview. Sample programs are available at the Microsoft Agent Web site at http://msdn.microsoft.com/msagent/.

Adding Microsoft Agent Functionality to Your Application

To access Microsoft Agent's server interfaces, Agent must already be installed on the target system. If you want to install Microsoft Agent as part of your application, you must have a valid distribution license for Agent. You can access the License Agreement from the Microsoft Agent Web site.

You can then download Agent's self-installing cabinet file from the Web site (using the Save rather than the Run option). You can include this file in your installation setup program. Whenever it is executed, it will automatically install Agent on the target system. For further details on installation, see the Microsoft Agent Distribution License Agreement. Installation other than using Agent's self-installing cabinet file, such as attempting to copy and register Agent component files, is not supported. This ensures consistent and complete installation. Note that the Microsoft Agent self-installing file will not install on Microsoft Windows 2000 (NT5) because that version of the operating system already includes its own version of Agent.

To successfully install Agent on a target system, you must also ensure that the target system has a recent version of the Microsoft Visual C++ runtime (Msvcrt.dll), Microsoft registration tool (Regsvr32.dll), and Microsoft COM dlls. The easiest way to ensure that the necessary components are on the target system is to require that Microsoft Internet Explorer 3.02 or later is installed. Alternatively, you can install the first two components which are available as part of Microsoft Visual C++. The necessary COM dlls can be installed as part of the Microsoft DCOM update, available at the Microsoft Web site. You can find further information and licensing information for these components at the Microsoft Web site.

Agent's language components can be installed the same way. Similarly, you can use this technique to install the ACS format of the Microsoft characters available for distribution from the Microsoft Agent Web site. The character files automatically install to the Microsoft Agent \Chars subdirectory.

Because Microsoft Agent's components are designed as operating system components, Agent may not be uninstalled. Similarly, where Agent is already installed as a part of the Windows operating system, the Agent self-installing cabinet may not install.

Once installed, to call Agent's interfaces, create an instance of the server and request a pointer to a specific interface that the server supports using the standard COM convention. In particular, the COM library provides an API function, CoCreateInstance, that creates an instance of the object and returns a pointer to the requested interface of the object. Request a pointer to the IAgent or IAgentEx interface in your CoCreateInstance call or in a subsequent call to QueryInterface.

The following code illustrates this in C/C++:

hRes = CoCreateInstance(CLSID_AgentServer,
                     NULL,
                     CLSCTX_SERVER,
                     IID_IAgentEx,
                     (LPVOID *)&pAgentEx);

If the Microsoft Agent server is running, this function connects to the server; otherwise, it starts up the server.

Note that the Microsoft Agent server interfaces often include extended interfaces that include an "Ex" suffix. These interfaces are derived from, and therefore include all the functionality of, their non-Ex counterparts. If you want to use any of the extended features, use the Ex interfaces.

Functions that take pointers to BSTRs allocate memory using SysAllocString. It is the caller's responsibility to free this memory using SysFreeString.

Loading Character and Animation Data

Once you have a pointer to the IAgentEx interface, you can use the Load method to load a character and retrieve its |AgentCharacterEx interface. There are three different possibilities for the Load path of a character. The first is compatible with Microsoft Agent 1.5 where the specified path is the full path and filename of a character file. The second possibility is to specify the filename only, in which case, Agent looks in its Chars directory. The last possibility is to supply an empty Variant parameter that causes the default character to be loaded.

   // Create a variant to store the filename of the character to load

const LPWSTR kpwszCharacter = L"merlinACS";

   VariantInit(&vPath);

   vPath.vt = VT_BSTR;
   vPath.bstrVal = SysAllocString(kpwszCharacter);

   // Load the character

   hRes = pAgentEx->Load(vPath, &lCharID, &lRequestID);

   // Get its IAgentCharacterEx interface

   hRes = pAgentEx->GetCharacterEx(lCharID, &pCharacterEx);

You can use this interface to access the character's methods:

   // Show the character.  The first parameter tells Microsoft
   // Agent to show the character by playing an animation.

   hRes = pCharacterEx->Show(FALSE, &lRequestID);

   // Make the character speak

   bszSpeak = SysAllocString(L"Hello World!");

   hRes = pCharacterEx->Speak(bszSpeak, NULL, &lRequestID);

   SysFreeString(bszSpeak);

When you no longer need Microsoft Agent services, such as when your client application shuts down, release its interfaces. Note that releasing the character interface does not unload the character. Call the Unload method to do this before releasing the IAgentEx interface:

// Clean up

if (pCharacterEx) {

   // Release the character interface

   pCharacterEx->Release();

   // Unload the character.  NOTE:  releasing the character
   // interface does NOT make the character go away.  You must
   // call Unload.

   pAgentEx->Unload(lCharID);
}
   
// Release the Agent

pAgentEx->Release();

VariantClear(&vPath);

Creating a Notification Sink

To be notified of events by Microsoft Agent, you must implement either the IAgentNotifySink or the IAgentNotifySinkEx interface, and create and register an object of that type following COM conventions:

// Create a notification sink

pSinkEx = new AgentNotifySinkEx;

pSinkEx->AddRef();

// And register it with Microsoft Agent

hRes = pAgentEx->Register((IUnknown *)pSinkEx, &lNotifySinkID);

Remember to unregister your notification sink when your application shuts down and releases Microsoft Agent's interfaces.

Accessing Services Using Java

You can also access Microsoft Agent services from a Java applet. Many of the functions accessible through the Microsoft Agent interfaces return values through parameters passed by reference. In order to pass these parameters from Java, it is necessary to create single-element arrays in your code and pass them as parameters to the appropriate function. If you're using Microsoft Visual J++™ and have run the Java Type Library Wizard on the Microsoft Agent server, refer to the summary.txt file to review which functions require array arguments. The procedure is similar to that in C; you use the IAgentEx interface to create an instance of the server, then load the character:

private IAgentEx            m_AgentEx = null;
private IAgentCharacterEx   m_Merlin[] = {null};
private int                 m_MerlinID[] = {-1};
private int                 m_RequestID[] = {0};
private final String        m_CharacterPath = " merlinACS";

public void start()
{
      // Start the Microsoft Agent Server

      m_AgentEx = (IAgentEx) new AgentServer();

      try
      {
         // The filespec parameter of the Load method is a 
         // COM variant to accept alternate Agent data providers.
         // We want a standard provider so we can just specify
         // the filespec for our character.

         Variant characterPath = new Variant();
         characterPath.putString(m_CharacterPath);

         // Load the character

         m_AgentEx.Load(characterPath,
                    m_MerlinID,
                    m_RequestID);
      }

The procedure is slightly different when loading characters from a HTTP remote location such as a Web site. In this case the Load method is asynchronous and will raise a COM exception of E_PENDING (0x8000000a). You will need to catch this exception and handle it correctly as is done in the following functions:

// Constants used in asynchronous character loads

private final int E_PENDING = 0x8000000a;
private final int NOERROR = 0;


// This function loads a character from the specified path.
// It correctly handles the loading of characters from
// remote sites.

// This sample doesn't care about the request id returned
// from the Load call.  Real production code might use the
// request id and the RequestComplete callback to check for
// a successful character load before proceeding.

public int LoadCharacter(Variant path, int[] id)
{
   int requestid[] = {-1};
   int hRes = 0;

   try
   {
      // Load the character

      m_AgentEx.Load(path, id, requestid);
   }
   catch(com.ms.com.ComException e)
   {
      // Get the HRESULT

      hRes = e.getHResult();
      
      // If the error code is E_PENDING, we return NOERROR

      if (hRes == E_PENDING)
         hRes = NOERROR;
   }

   return hRes;
}

public void start()
{
   if (LoadCharacter(characterPath, m_MerlinID) != NOERROR)
   {
      stop();
      return;
   }

   // Other initialization code here

   .
   .
   .
}

Then get the IAgentCharacterEx interface that enables you to access its methods:

// Get the IAgentCharacterEx interface for the loaded
// character by passing its ID to the Agent server.

m_AgentEx.GetCharacterEx(m_MerlinID[0], m_Merlin);

// Show the character

m_Merlin[0].Show(FALSE, m_RequestID);

// And speak hello

m_Merlin[0].Speak("Hello World!", "", m_RequestID);

Similarly, to be notified of events, you must implement either the IAgentNotifySink or/P>

...
// Declare an Agent Notify Sink so that we can get
// notification callbacks from the Agent server.

private AgentNotifySinkEx m_SinkEx = null;
private int            m_SinkID[] = {-1};

public void start()
   {
   ...
   // Create and register a notify sink

   m_SinkEx = new AgentNotifySinkEx();

   m_AgentEx.Register(m_SinkEx, m_SinkID);
   …
   // Give our notify sink access to the character

   m_SinkEx.SetCharacter(m_Merlin[0]);
   ...
   }

In order to access Microsoft Agent from a Java applet, you must generate Java classes that you install with the applet. You can use the Visual J++ Java Type Library Wizard, for example, to generate these files. If you plan to host the applet on a Web page, you will need to build a signed Java CAB inclusive of the generated class files that download with the page. The class files are necessary to access the Microsoft Agent Server since it is a COM object, that executes outside of the Java sandbox. To learn more about Trust-Based Security for Java, see http://www.microsoft.com/java/security/ .

Accessing Speech Services

Although Microsoft Agent's services include support for speech input, a compatible command-and-control speech recognition engine must be installed to access Agent's speech input services. Similarly, if you want to use Microsoft Agent's speech services to support synthesized speech output for a character, you must install a compatible text-to-speech (TTS) speech engine for your character. Because Microsoft Agent's speech services are based on the Microsoft Speech API (SAPI), you can use any engines that compatibly support the required speech interfaces. Further information on the availability and use of speech recognition and text-to-speech engines is at the Microsoft Agent Downloads for Developers page.

To enable speech input support in your application, define a Command object and set its Voice property. Microsoft Agent will automatically load speech services, so that when the user presses the Listening key or you call Listen, the speech recognition engine will be loaded. By default the character's language ID will determine which engine is loaded. Agent attempts to load the first engine that SAPI returns as matching this language. Use IAgentCharacterEx::SetSRModeID if you want to load a specific engine.

To enable text-to-speech output, use the Speak method. Microsoft Agent will automatically attempt to load an engine that matches the character's language ID. If the character's definition includes a specific TTS engine mode ID and that engine is available and matches the character's language ID, Agent loads that engine for the character. If not, Agent loads the first TTS engine that SAPI returns as matching the character's language setting. You can also use IAgentCharacterEx::SetTTSModeID to load a specific engine.

Typically, Microsoft Agent loads a speech recognition engine when the Listening mode is initiated and loads a text-to-speech engine when Speak is first called. However, if you want to preload the speech engine, you can do this by querying the properties related to the speech interfaces. For example, calling IAgentCharacterEx::GetSRModeID or IAgentCharacterEx::GetTTSModeID will attempt to load that type of engine.

Reference

This reference contains the following sections:

Interfaces

Events

Interfaces

Microsoft Agent defines interfaces that allow applications to access its services, enabling an application to control the animation of a character, support user input events, and specify output.

All the Microsoft Agent interfaces are defined in header (.h) files.

IAgent

IAgent defines an interface that allows applications to load characters, receive events, and check the current state of the Microsoft Agent Server. These functions are also available from IAgentEx.

The GetSuspended method included in previous versions is obsolete and returns False for backward compatibility.

Methods in Vtable Order

IAgent Methods	Description
Load	Loads a character's data file.
Unload	Unloads a character's data file.
Register	Registers a notification sink for the client.
Unregister	Unregisters a client's notification sink.
GetCharacter	Returns the IAgentCharacter interface for a loaded character.

IAgent::GetCharacter

HRESULT GetCharacter(
   long dwCharID  // character ID
);

Retrieves the IAgentCharacter for a loaded character.

Returns S_OK to indicate the operation was successful.

DwCharID

The character's ID.

IAgent::Load

HRESULT Load(
   VARIANT vLoadKey,  // data provider
   long * pdwCharID,  // address of a variable for character ID
   long * pdwReqID    // address of a variable for request ID
);

Loads a character into the Characters collection.

Returns S_OK to indicate the operation was successful.

vLoadKey

A variant datatype that must be one of the following:

filespec	The local file location of the specified character's definition file.
URL	The HTTP address for the character's definition file.
provider	An alternate character definition provider.

pdwCharID

Address of a variable that receives the character's ID.

pdwReqID

Address of a variable that receives the Load request ID.

You can load characters from the Microsoft Agent subdirectory by specifying a relative path (one that does not include a colon or leading slash character). This prefixes the path with Agent's characters directory (located in the localized %windows%\msagent directory). You can also use a relative address to specify your own directory in Agent's Chars directory.

You cannot load the same character (a character having the same GUID) more than once from a single connection. Similarly, you cannot load the default character and other characters at the same time from a single connection. The default character could be the same as the other character. However, you can create another connection (using CoCreateInstance) and load the same character.

Microsoft Agent's data provider supports loading character data stored as a single structured file (ACS) with character data and animation data together, or as separate character data (ACF) and animation (ACA) files. Generally, use the single structured ACS file to load a character that is stored on a local disk drive or network and accessed using conventional file protocol (such as UNC pathnames). Use the separate ACF and ACA files when you want to load the animation files individually from a remote site where they are accessed using HTTP protocol.

For ACS files, using the Load method provides access a character's animations; once loaded, you can use the Play method to animate the character. For ACF files, you also use the Prepare method to load animation data. The Load method does not support downloading ACS files from an HTTP site.

Loading a character does not automatically display the character. Use the Show method first to make the character visible.

IAgent::Register

HRESULT Register(
   IUnknown * punkNotifySink  // IUnknown address for client notification sink
   long * pdwSinkID           // address of the notification sink ID
);

Registers a notification sink for the client application.

Returns S_OK to indicate the operation was successful.

IUnknown

Address of IUnknown for your notification sink interface.

pdwSinkID

Address of notification sink ID (used to unregister the notification sink).

You need to register your notification sink (also known as a notify sink or event sink) to receive events from the Microsoft Agent server.

IAgentEx

IAgentEx is derived from the IAgent interface. It includes all the IAgent methods as well as provides access to additional functions.

Methods in Vtable Order

IAgentEx Methods	Description
ShowDefaultCharacterProperties	Displays the default character properties.
GetVersion	Returns the version number for Microsoft Agent (server).

IAgentEx::ShowDefaultCharacterProperties

HRESULT ShowDefaultCharacterProperties(
   short x,          // x-coordinate of window
   short y,          // y-coordinate of window
   long bUseDefault  // default position flag
);

Displays default character properties window.

Returns S_OK to indicate the operation was successful.

The x-coordinate of the window in pixels, relative to the screen origin (upper left).

The y-coordinate of the window in pixels, relative to the screen origin (upper left).

bUseDefault

Default position flag. If this parameter is True, Microsoft Agent displays the property sheet window for the default character at the last location it appeared.

Note For Windows 2000, it may be necessary to call the new AllowSetForegroundWindow API to ensure that this window becomes the foreground window. For more information about setting the foreground window under Windows 2000, see the Win32Ž documentation.

IAgentEx::GetVersion

HRESULT GetVersion(
   short * psMajor,  // address of major version
   short * psMinor   // address of minor version
);

Retrieves the version number of Microsoft Agent server.

Returns S_OK to indicate the operation was successful.

psMajor

Address of a variable that receives the major version.

psMinor

Address of a variable that receives the minor version.

IAgentCharacter

IAgentCharacter defines an interface that allows applications to query character properties and play animations. These functions are also available from IAgentCharacterEx. You can use some method return request IDs to track their status in the character's queue and to synchronize your code with the character's current animation state.

Methods in Vtable Order

IAgentCharacter Methods	Description
GetVisible	Returns whether the character (frame) is currently visible.
SetPosition	Sets the position of the character frame.
GetPosition	Returns the position of the character frame.
SetSize	Sets the size of the character frame.
GetSize	Returns the size of the character frame.
GetName	Returns the name of the character.
GetDescription	Returns the description for the character.
GetTTSSpeed	Returns the current TTS output speed setting for the character.
GetTTSPitch	Returns the current TTS pitch setting for the character.
Activate	Sets whether a client is active or a character is topmost.
SetIdleOn	Sets the server's idle processing.
GetIdleOn	Returns the setting of the server's idle processing.
Prepare	Retrieves animation data for the character.
Play	Plays a specified animation.
Stop	Stops an animation for a character.
StopAll	Stops all animations for a character.
Wait	Holds the character's animation queue.
Interrupt	Interrupts a character's animation.
Show	Displays the character and plays the character's Showing state animation.
Hide	Plays the character's Hiding state animation and hides the character's frame.
Speak	Plays spoken output for the character.
MoveTo	Moves the character frame to the specified location.
GestureAt	Plays a gesturing animation based on the specified location.
GetMoveCause	Retrieves the cause of the character's last move.
GetVisibilityCause	Retrieves the cause of the last change to the character's visibility state.
HasOtherClients	Retrieves whether the character has other current clients.
SetSoundEffectsOn	Determines whether a character animation's sound effects play.
GetSoundEffectsOn	Retrieves whether a character's sound effects setting is enabled.
SetName	Sets the character's name.
SetDescription	Sets the character's description.
GetExtraData	Retrieves additional data stored with the character.

IAgentCharacter::Activate

HRESULT Activate(
   short sState, // topmost character or client setting
);

Sets whether a client is active or a character is topmost.

Returns S_OK to indicate the operation was successful.
Returns S_FALSE to indicate the operation was not successful.

sState

You can specify the following values for this parameter:

0 Set as not the active client.

1 Set as the active client.

2 Make the topmost character.

When multiple characters are visible, only one of the characters receives speech input at a time. Similarly, when multiple client applications share the same character, only one of the clients receives mouse input (for example, Microsoft Agent control click or drag events) at a time. The character set to receive mouse and speech input is the topmost character and the client that receives input is the character's active client. (The topmost character's window also appears at the top of the character window's z-order.) Typically, the user determines which character is topmost by explicitly selecting it. However, topmost activation also changes when a character is shown or hidden (the character becomes or is no longer topmost, respectively.)

You can also use this method to explicitly manage when your client receives input directed to the character, such as when your application itself becomes active. For example, setting State to 2 makes the character topmost, and your client receives all mouse and speech input events generated from user interaction with the character. Therefore, it also makes your client the input-active client of the character. However, you can also set the active client for a character without making the character topmost, by setting State to 1. This enables your client to receive input directed to that character when the character becomes topmost. Similarly, you can set your client to not be the active client (to not receive input) when the character becomes topmost, by setting State to 0. You can determine if a character has other current clients using IAgentCharacter::HasOtherClients.

Avoid calling this method directly after a Show method. Show automatically sets the input-active client. When the character is hidden, the Activate call may fail, if it gets processed before the Show method completes.

Attempting to call this method with the State parameter set to 2 (when the specified character is hidden) will fail. Similarly, if you set State to 0, and your application is the only client, this call fails. A character must always have a topmost client.

Note Calling this method with State set to 1 does not typically generate an AgentNotifySink::ActivateInputState event unless there are no other characters loaded or your application is already input-active.

IAgentCharacter::GestureAt

HRESULT GestureAt(
   short x,         // x-coordinate of specified location
   short y,         // y-coordinate of specified location
   long * pdwReqID  // address of a request ID
);

Plays the associated Gesturing state animation based on the specified location.

Returns S_OK to indicate the operation was successful. When the function returns, pdwReqID contains the ID of the request.

The x-coordinate of the specified location in pixels, relative to the screen origin (upper left).

The y-coordinate of the specified location in pixels, relative to the screen origin (upper left).

pdwReqID

Address of a variable that receives the GestureAt request ID.

The server automatically determines and plays the appropriate gesturing animation based on the character's current position and the specified location. When using the HTTP protocol to access character and animation data, use the Prepare method to ensure that the animations are available before calling this method.

IAgentCharacter::GetDescription

HRESULT GetDescription(
   BSTR * pbszDescription   // address of buffer for character description
);

Retrieves the description of the character.

Returns S_OK to indicate the operation was successful.

pbszDescription

The address of a BSTR that receives the value of the description for the character. A character's description is defined when it is compiled with the Microsoft Agent Character Editor. The description setting is optional and may not be supplied for all characters.

IAgentCharacter::GetExtraData

HRESULT GetExtraData(
   BSTR * pbszExtraData   // address of buffer for additional character data
);

Retrieves additional data stored as part of the character.

Returns S_OK to indicate the operation was successful.

pbszExtraData

The address of a BSTR that receives the value of the additional data for the character. A character's additional data is defined when it is compiled with the Microsoft Agent Character Editor. A character developer can supply this string by editing the .ACD file for a character. The setting is optional and may not be supplied for all characters, nor can the data be defined or changed at run time. In addition, the meaning of the data supplied is defined by the character developer.

IAgentCharacter::GetIdleOn

HRESULT GetIdleOn(
   long * pbOn  // address of idle processing flag
);

Indicates the automatic idle processing state for a character.

Returns S_OK to indicate the operation was successful.

pbOn

Address of a variable that receives True if the Microsoft Agent server automatically plays Idling state animations for a character and False if not.

IAgentCharacterEx

IAgentCharacterEx derives from the IAgentCharacter interface. It includes all the IAgentCharacter methods as well as provides access to additional functions.

Methods in Vtable Order

IAgentCharacterEx Methods	Description
ShowPopupMenu	Displays the pop-up menu for the character.
SetAutoPopupMenu	Sets whether the server automatically displays the character's pop-up menu.
GetAutoPopupMenu	Returns whether the server automatically displays the character's pop-up menu.
GetHelpFileName	Returns the Help filename for the character.
SetHelpFileName	Sets the Help filename for the character.
SetHelpModeOn	Sets Help mode on.
GetHelpModeOn	Returns whether Help mode is on.
SetHelpContextID	Sets the HelpContextID for the character.
GetHelpContextID	Returns the HelpContextID for the character.
GetActive	Returns the active state for the character.
Listen	Sets the listening state for the character.
SetLanguageID	Sets the language ID for the character.
GetLanguageID	Returns the language ID for the character.
GetTTSModeID	Returns the TTS mode ID set for the character.
SetTTSModeID	Sets the TTS mode ID for the character.
GetSRModeID	Returns the current speech recognition engine's mode ID.
SetSRModeID	Sets the speech recognition engine.
GetGUID	Returns the character's identifier.
GetOriginalSize	Returns the original size of the character frame.
Think	Displays the specified text in the character's "thought" balloon.
GetVersion	Returns the version of the character.
GetAnimationNames	Returns the names of the animations for the character.
GetSRStatus	Returns the conditions necessary to support speech input.

IAgentCharacterEx::GetActive

HRESULT GetActive(
   short * psState  // address of active state setting
);

Retrieves whether your client application is the active client of the character and whether the character is topmost.

Returns S_OK to indicate the operation was successful.

psState

Address of a variable that receives one of the following values for the state setting:

const unsigned short ACTIVATE_NOTACTIVE = 0;	Your client is not the active client of the character.
const unsigned short ACTIVATE_ACTIVE = 1;	Your client is the active client of the character.
const unsigned short ACTIVATE_INPUTACTIVE = 2;	Your client is input-active (active client of the topmost character).

This setting lets you know whether you are the active client of the character or whether your character is the active client of the character. When multiple client applications share the same character, the active client of the character receives mouse input (for example, Microsoft Agent control click or drag events). Similarly, when multiple characters are displayed, the active client of the topmost character (also known as the input-active client) receives IAgentNotifySink::Command events.

Use the Activate method to set whether your application is the active client of the character or to make your application the input active client (which also makes the character topmost).

IAgentCharacterEx::GetAnimationNames

HRESULT GetAnimationNames(
   IUnknown ** punkEnum // address of IUnknown inteface
);

Retrieves the animation names for a character.

Returns S_OK to indicate the operation was successful.

IUnknown

The address of the IUnknown interface for the character's animation collection.

This function enables you to enumerate the names of the animations for a character. Items in the collection have no properties, so individual items cannot be accessed directly.

Note For ACF characters, the collection returns all the animations that have been defined for the character, adding to the ones that have been retrieved with the Get method.

IAgentCharacterEx::GetAutoPopupMenu

HRESULT GetAutoPopupMenu(
   long * pbAutoPopupMenu  // address of auto pop-up menu display setting
);

Retrieves whether the server automatically displays the character's pop-up menu.

Returns S_OK to indicate the operation was successful.

pbAutoPopupMenu

Address of a variable that receives True if the Microsoft Agent server automatically handles displaying the character's pop-up menu and False if not.

When this property is set to False, your application must display the pop-up menu using IAgentCharacter::ShowPopupMenu method.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

IAgentCharacterEx::GetGUID

HRESULT GetGUID(
   BSTR * pbszGUID  // address of character's ID
);

Retrieves the unique ID for the character.

Returns S_OK to indicate the operation was successful.

pbszGUID

Address of a BSTR that receives the ID for the character.

The property returns a string representation of the GUID (formatted with braces and dashes) that the server uses to uniquely identify the character. A character identifier is set when it is compiled with the Microsoft Agent Character Editor. The property is read-only.

IAgentCharacterEx::GetHelpContextID

HRESULT GetHelpContextID(
   long * pulHelpID  // address of character's help topic ID
);

Retrieves the HelpContextID for the character.

Returns S_OK to indicate the operation was successful.

pulHelpID

Address of a variable that receives the context number of the help topic for the character.

If you've created a WindowsŽ Help file for your application and set the character's HelpFile property, Microsoft Agent automatically calls Help when HelpModeOn is set to True and the user selects the character. If there is a context number in the HelpContextID, Agent calls Help and searches for the topic identified by the current context number. The current context number is the value of HelpContextID for the character.

IAgentCharacterEx::GetHelpContextID returns the HelpContextID you set for the character. It does not return the HelpContextID set by other clients.

Note Building a Help file requires the Microsoft Windows Help Compiler.

IAgentCharacterEx::GetHelpFileName

HRESULT GetHelpFileName(
   BSTR * pbszName  // address of Help filename
);

Retrieves the HelpFileName for a character.

Returns S_OK to indicate the operation was successful.

pbszName

Address of a variable that receives the Help filename for the character.

If you've created a Windows Help file for your application and set the character's HelpFile property, Microsoft Agent automatically calls Help when HelpModeOn is set to True and the user clicks the character or selects a command from its pop-up menu. If there is a context number in the selected command's HelpContextID property, Help displays a topic corresponding to the current Help context; otherwise it displays "No Help topic associated with this item."

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

Note Building a Help file requires the Microsoft Windows Help Compiler.

IAgentCharacterEx::GetHelpModeOn

HRESULT GetHelpModeOn(
   long * pbHelpModeOn  // address of help mode setting
);

Retrieves whether context-sensitive Help mode is on for the character.

Returns S_OK to indicate the operation was successful.

pbHelpModeOn

Address of a variable that receives True if Help mode is on for the character and False if not.

When this property is set to True, the mouse pointer changes to the context-sensitive Help image when moved over the character or over the pop-up menu for the character. When the user clicks or drags the character or clicks an item in the character's pop-up menu, the server triggers the IAgentNotifySinkEx::HelpComplete event and exits Help mode.

In Help mode, the server does not send the IAgentNotifySink::Click, IAgentNotifySink::DragStart, IAgentNotifySink::DragComplete, and IAgentNotifySink::Command events, unless GetAutoPopupMenu property returns True. In that case, the server will send the IAgentNotifySink::Click event (does not exit Help mode), but only for the right mouse button to enable you to display the pop-up menu.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

IAgentCharacterEx::GetLanguageID

HRESULT GetLanguageID(
   long * plangID  // address of language ID setting
);

Retrieves the language ID set for the character.

Returns S_OK to indicate the operation was successful.

plangID

Address of a variable that receives the language ID setting for the character.

A Long integer specifying the language ID for the character. The language ID (LANGID) for a character is a 16-bit value defined by Windows, consisting of a primary language ID and a secondary language ID. The following examples are values for some languages. To determine the values other languages, see the Win32 SDK documentation .

Arabic (Saudi)	0x0401	Italian	0x0410
Basque	0x042d	Japanese	0x0411
Chinese (Simplified)	0x0804	Korean	0x0412
Chinese (Traditional)	0x0404	Norwegian	0x0414
Croatian	0x041A	Polish	0x0415
Czech	0x0405	Portuguese	0x0816
Danish	0x0406	Portuguese (Brazilian)	0x0416
Dutch	0x0413	Romanian	0x0418
English (British)	0x0809	Russian	0x0419
English (US)	0x0409	Slovakian	0x041B
Finnish	0x040B	Slovenian	0x0424
French	0x040C	Spanish	0x0C0A
German	0x0407	Swedish	0x041D
Greek	0x0408	Thai	0x041E
Hebrew	0x040D	Turkish	0x041F
Hungarian	0x040E

If you do not set this language ID for the character, the character's language ID will be the current system language ID.

This setting also determines the language for TTS output, word balloon text, the commands in the character's pop-up menu, and speech recognition engine. To determine if there is a compatible speech recognition engine available for the character's language, use IAgentCharacterEx::GetSRModeID or IAgentCharacterEx::GetTTSModeID.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

Note If the language ID is set to a language that supports bidirectional text (such as Arabic or Hebrew), but the system running your application does not have bidirectional support installed, text will appear in the word balloon in logical rather than display order.

IAgentCharacterEx::GetOriginalSize

HRESULT GetOriginalSize(
   long * plWidth,  // address of variable for character width 
   long * plHeight  // address of variable for character height
);

Retrieves the original size of the character's animation frame.

Returns S_OK to indicate the operation was successful.

plWidth

Address of a variable that receives the original width of the character animation frame in pixels.

plHeight

Address of a variable that receives the original height of the character animation frame in pixels.

This call returns the original size of the character frame as built in the Microsoft Agent Character Editor.

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 Voice 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 Voice 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 and the character is visible. Therefore, you will typically want to set the Caption, VoiceCaption, 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 Voice Commands Window. When the user switches to your client by choosing its Commands entry, the server automatically makes your client input-active, notifying your client application using the IAgentNotifySink::ActivateInputState and makes the Commands in its collection available. The server also notifies the client that is no longer input-active with the IAgentNotifySink::ActivateInputState event. 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.

A client can also explicitly request to make itself the input-active client using the IAgentCharacter::Activate method. This method also supports setting your application to not be the input-active client. You may want to use this method when sharing a character with another application, setting your application to be input-active when your application window gets focus and not input-active when it loses focus.

Similarly, you can use IAgentCharacter::Activate to set your application to be (or not be) the active client of the character. The active client is the client that receives input when its character is the topmost character. When this status changes, the server notifies your application with the IAgentNotifySinkEx::ActiveClientChange event.

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 Voice 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. These functions are also available from IAgentCommandsEx.

A Commands collection can appear as a command in both the pop-up menu and the Voice 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.

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 the same as a null string.

**The command is still voice-accessible.

Methods in Vtable Order

IAgentCommands Methods	Description
GetCommand	Retrieves a Command object from the Commands collection.
GetCount	Returns the value of the number of Commands in a Commands collection.
SetCaption	Sets the value of the Caption property for a Commands collection.
GetCaption	Returns the value of the Caption property of a Commands collection.
SetVoice	Sets the value of the Voice property for a Commands collection.
GetVoice	Returns the value of the Voice property of a Commands collection.
SetVisible	Sets the value of the Visible property for a Commands collection.
GetVisible	Returns the value of the Visible property of a Commands collection.
Add	Adds a Command object to a Commands collection.
Insert	Inserts a Command object in a Commands collection.
Remove	Removes a Command object in a Commands collection.
RemoveAll	Removes all Command objects from a Commands collection.

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.

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.

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.

IAgentCommandsEx

IAgentCommandsEx defines an interface that extends the IAgentCommands interface.

Methods in Vtable Order

IAgentCommandsEx Methods	Description
SetDefaultID	Sets the default command for the character's pop-up menu.
GetDefaultID	Returns the default command for the character's pop-up menu.
SetHelpContextID	Sets the context-sensitive help topic ID for a Commands object
GetHelpContextID	Returns the context-sensitive help topic ID for a Command object .
SetFontName	Sets the font to use in the character's pop-up menu.
GetFontName	Returns the font used in the character's pop-up menu.
SetFontSize	Sets the font size to use in the character's pop-up menu.
GetFontSize	Returns the font size used in the character's pop-up menu.
SetVoiceCaption	Sets the voice caption for the character's Commands object.
GetVoiceCaption	Returns the voice caption for the character's Commands object.
AddEx	Adds a Command object to a Commands collection.
InsertEx	Inserts a Command object in a Commands collection.
SetGlobalVoiceCommandsEnabled	Enables the voice grammar for Agent's global commands.
GetGlobalVoiceCommandsEnabled	Returns whether the voice grammar for Agent's global commands is enabled.

IAgentCommandsEx::AddEx

HRESULT AddEx(
   BSTR bszCaption,       // Caption setting for Command
   BSTR bszVoice,         // Voice setting for Command
   BSTR bszVoiceCaption,  // VoiceCaption setting for Command
   long bEnabled,         // Enabled setting for Command
   long bVisible,         // Visible setting for Command
   long ulHelpID,         // HelpContextID 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.

bszVoiceCaption

A BSTR that specifies the value of the VoiceCaption text displayed 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).

ulHelpID

The context number of the help topic associated with the Command object; used to provide context-sensitive Help for the command.

pdwID

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

IAgentCommandsEx::AddEx extends IAgentCommands::Add by including the HelpContextID property. You can also set the property using IAgentCommandsEx::SetHelpContextID

IAgentCommandsEx::GetDefaultID

HRESULT GetDefaultID(
   long * pdwID  // address of default command's ID
);

Retrieves the ID of the default command in a Commands collection.

Returns S_OK to indicate the operation was successful.

pdwID

Address of a variable that receives the ID of the Command set as the default.

This property returns the current default Command object in your Commands collection. The default command is bold in the character's pop-up menu. However, setting the default command does not change command handling or double-click events.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

See also IAgentCommandsEx::SetDefaultID

IAgentCommandsEx::GetFontName

HRESULT GetFontName(
   BSTR * pbszFontName  // address of variable for font displayed 
);                      // in character's pop-up menu

Retrieves the value for the font displayed in the character's pop-up menu.

Returns S_OK to indicate the operation was successful.

pbszFontName

The address of a BSTR that receives the font name displayed in the character's pop-up menu.

The font name returned corresponds to the font used to display text in the character's pop-up menu when your client application is input-active. The default value for the font setting is based on the menu font setting for the character's language ID setting, or if not set, the user default language ID setting.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

IAgentCommandsEx::GetFontSize

HRESULT GetFontSize(
   long * plFontSize  // address of variable for font size 
);                    // for font displayed in character's pop-up menu

Retrieves the value for the size of the font displayed in the character's pop-up menu.

Returns S_OK to indicate the operation was successful.

plFontSize

The address of a value that receives the size of the font.

The point size of the font returned corresponds to the size defined to display text in the character's pop-up menu when your client is input-active. The default value for the font setting is based on the menu font setting for the character's language ID setting, or if not set, the user default language setting.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

IAgentCommandsEx::GetGlobalVoiceCommandsEnabled

HRESULT GetGlobalVoiceCommandsEnabled(
     // address of the global voice command setting
);

Retrieves whether the voice grammar for Agent's global commands is enabled.

Returns S_OK to indicate the operation was successful.

pbEnabled

The address that receives True if the voice grammar for Agent's global commands is enabled, False if disabled.

Microsoft Agent automatically adds voice parameters (grammar) for opening and closing the Voice Commands Window and for showing and hiding the character. When this method returns False, any voice parameters for these commands as well as the voice parameters for the Caption of other clients' Commands objects are not included in the grammar. This enables you to eliminate these from your client's current active grammar. However, this setting does not reflect the inclusion of these commands in the character's pop-up menu.

IAgentCommandsEx::GetHelpContextID

HRESULT GetHelpContextID(
   long * pulHelpID  // address of Commands object help topic ID
);

Retrieves the HelpContextID for a Commands object.

Returns S_OK to indicate the operation was successful.

pulHelpID

Address of a variable that receives the context number of the help topic for the Commands object.

If you've created a Windows Help file for your application and set the character's HelpFile property, Microsoft Agent automatically calls Help when HelpModeOn is set to True and the user selects your Commands object. If there is a context number in the HelpContextID, Agent calls Help and searches for the topic identified by the current context number. The current context number is the value of HelpContextID for the Commands object.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

Note Building a Help file requires the Microsoft Windows Help Compiler.

IAgentCommandsEx::GetVoiceCaption

HRESULT GetVoiceCaption(
   BSTR * pbszVoiceCaption  // address of command's voice caption
);

Retrieves the VoiceCaption for a Commands object.

Returns S_OK to indicate the operation was successful.

pbszVoiceCaption

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

The text returned is that set for your Commands object and appears in the Voice Commands window when your client application is input-active.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

IAgentCommandsEx::InsertEx

HRESULT InsertEx(
   BSTR bszCaption,       // Caption setting for Command
   BSTR bszVoice,         // Voice setting for Command
   BSTR bszVoiceCaption,  // VoiceCaption setting for Command
   long bEnabled,         // Enabled setting for Command
   long bVisible,         // Visible setting for Command
   long ulHelpID,         // HelpContextID 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.

bszVoiceCaption

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

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).

ulHelpID

The context number of the help topic associated with the Command object; used to provide context-sensitive Help for the command.

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.

IAgentCommandsEx::InsertEx extends IAgentCommands::Insert by including the HelpContextID property. You can also set the property using IAgentCommandsEx::SetHelpContextID

IAgentCommandsEx::SetDefaultID

HRESULT SetDefaultID(
   long dwID,  // default command's ID
);

Sets the ID of the default command in a Commands collection.

Returns S_OK to indicate the operation was successful.

dwID

The ID for the Command to be set as the default.

This property sets the default Command object set in your Commands collection. The default command is bold in the character's pop-up menu. However, setting the default command does not actually change command handling or double-click events.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

See also IAgentCommandsEx::GetDefaultID

IAgentCommandsEx::SetFontName

HRESULT SetFontName(
   BSTR bszFontName  // font to be displayed in character's pop-up menu
);

Sets the font displayed in the character's pop-up menu.

Returns S_OK to indicate the operation was successful.

bszFontName

A BSTR that sets the font displayed in the character's pop-up menu.

This property determines the font used to display text in the character's pop-up menu. The default value for the font setting is based on the menu font setting for the character's language ID setting -- or if that's not set -- the user default language ID setting.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

IAgentCommandsEx::SetFontSize

HRESULT SetFontSize(
   long lFontSize  // font size displayed in character's pop-up menu
);

Sets the size of the font displayed in the character's pop-up menu.

Returns S_OK to indicate the operation was successful.

lFontSize

The size of the font.

This property determines the point size of the font used to display text in the character's pop-up menu when your client application is input-active. The default value for the font setting is based on the menu font setting for the character's language ID setting -- or if that's not set -- the user default language setting. If not input-active, your client application's Commands Caption text appears in the point size specified for the input-active client.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

IAgentCommandsEx::SetGlobalVoiceCommandsEnabled

HRESULT SetGlobalVoiceCommandsEnabled(
   // Enabled setting for Agent's global voice commands
);

Sets the Enabled property for the voice grammar of Microsoft Agent's global commands.

Returns S_OK to indicate the operation was successful.

bEnable

A Boolean value that sets whether the voice grammar of Agent's global commands is enabled. True enables the voice grammar; False disables it.

Microsoft Agent automatically adds voice parameters (grammar) for opening and closing the Voice Commands Window and for showing and hiding the character. When set to False, Agent disables any voice parameters for these commands as well as the voice parameters for the Caption of other client's Commands objects. This enables you to eliminate these from your client's current active grammar. However, because this potentially blocks voice access to other clients, reset this property to True after processing the user's voice input.

Disabling the property does not affect the character's pop-up menu. The global commands added by the server will still appear. You cannot remove them from the pop-up menu.

IAgentCommandsEx::SetHelpContextID

HRESULT SetHelpContextID(
   long ulHelpID  // ID for help topic
);

Sets the HelpContextID for a Command object.

Returns S_OK to indicate the operation was successful.

ulHelpID

The context number of the help topic associated with the Command object; used to provide context-sensitive Help for the command.

If you've created a Windows Help file for your application and set this in the character's HelpFile property. Agent automatically calls Help when HelpModeOn is set to True and the user selects the command. If there is a context number in the HelpContextID, Agent calls Help and searches for the topic identified by the current context number. The current context number is the value of HelpContextID for the command. If there is a context number in the selected command's HelpContextID property, Help displays a topic corresponding to the current Help context; otherwise it displays "No Help topic associated with this item."

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

Note Building a Help file requires the Microsoft Windows Help Compiler.

IAgentCommandsEx::SetVoiceCaption

HRESULT SetVoiceCaption(
   BSTR bszVoiceCaption  // voice caption text
);

Sets the VoiceCaption text displayed for the Commands object.

Returns S_OK to indicate the operation was successful.

bszVoiceCaption

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

If you define a Command object in a Commands collection and set its Voice property, you will typically also set its VoiceCaption property. This text will appear in the Voice Commands Window when your client application is input-active and the character is visible. If this property is not set, the setting for the Caption property determines the text displayed. When neither the VoiceCaption or Caption property is set, the command does not appear in the Voice Commands Window.

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 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 Caption 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.

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.

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.

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.

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.

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.

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.

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 Voice Commands Window. If its Visible property is set to True, it appears in the character's pop-up menu.

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.

Setting the Caption property for a Command defines how it will appear on the character's pop-up menu when its Visible property is set to True and your application is not the input-active client. To specify an access key (unlined mnemonic) for your Caption, include an ampersand (&) character before that character. To make it selectable, its Enabled property must be set to True.

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.

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.

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 Voice Commands Window, you must set its Voice property.

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.

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 VoiceCaption property set to appear in the Voice Commands Window. (For backward compatibility, if there is no VoiceCaption, the Caption setting is used.)

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.

   "please* try this"

The following grammar format excludes "try this" because the + operator defines at least one instance of "please":

   "please+ try this"

   "New York+"

Therefore, you will typically want to use these operators with the grouping characters. For example, the following grammar includes both "New York" and "New York New York":

   "(New York)+"

Repetition operators are useful when you want to compose a grammar that includes a repeated sequence such as a phone number or specification of a list of items:

   "call (one|two|three|four|five|six|seven|eight|nine|zero|oh)*"
   "I'd like (cheese|pepperoni|pineapple|canadian bacon|mushrooms|and)+"

Although the operators can also be used with the square brackets (an optional grouping character), doing so may reduce the efficiency of Agent's processing of the grammar.

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.

Setting the Voice property for a Command automatically enables Agent's speech services, making the Listening key and Listening Tip available. However, it does not load the speech recognition engine.

Note The grammar features available may depend on the speech recognition engine. You may want to check with the engine's vendor to determine what grammar options are supported. Use IAgentCharacterEx::SRModeID to specify an engine.

IAgentCommandEx

IAgentCommandEx is derived from the IAgentCommand interface. It includes all the IAgentCommand methods and provides access to additional functions.

Methods in Vtable Order

IAgentCommandEx Methods	Description
SetHelpContextID	Sets the context-sensitive help topic ID for a Command object.
GetHelpContextID	Returns the context-sensitive help topic ID for a Command object.
SetVoiceCaption	Sets the voice caption for a Command object.
GetVoiceCaption	Returns the voice caption for a Command object.

IAgentCommandEx::GetHelpContextID

HRESULT GetHelpContextID(
   long * pulID  //  address of command's help topic ID
);

Retrieves the HelpContextID for a Command object.

Returns S_OK to indicate the operation was successful.

pulID

Address of a variable that receives the context number of the help topic associated with the Command object.

If you've created a Windows Help file for your application and set your character's HelpFile property to this file, Microsoft Agent automatically calls Help when HelpModeOn is set to True and the user selects the command. If there is a context number in the HelpContextID, Agent calls Help and searches for the topic identified by the current context number. The current context number is the value of HelpContextID for the command.

Note Building a Help file requires the Microsoft Windows Help Compiler.

IAgentCommandEx::GetVoiceCaption

HRESULT GetVoiceCaption(
   BSTR * pbszVoiceCaption  // address of command's voice caption text
);

Retrieves the VoiceCaption for a Command.

Returns S_OK to indicate the operation was successful.

pbszVoiceCaption

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

The VoiceCaption is the text that appears for a Command object in the Voice Commands Window when your client application is input-active.

IAgentCommandEx::SetHelpContextID

HRESULT SetHelpContextID(
   long ulID  //  ID for help topic
);

Sets the HelpContextID for a Command object.

Returns S_OK to indicate the operation was successful.

ulID

The context number of the help topic associated with the Command object; used to provide context-sensitive Help for the command.

If you've created a Windows Help file for your application and set this in the character's HelpFile property. Microsoft Agent automatically calls Help when HelpModeOn is set to True and the user selects the command. If there is a context number in the HelpContextID, Agent calls Help and searches for the topic identified by the current context number. The current context number is the value of HelpContextID for the command.

Note Building a Help file requires the Microsoft Windows Help Compiler.

IAgentCommandEx::SetVoiceCaption

HRESULT SetVoiceCaption(
   BSTR bszVoiceCaption  // voice caption text
);

Sets the VoiceCaption text displayed for a Command.

Returns S_OK to indicate the operation was successful.

bszVoiceCaption

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

If you define a Command object in a Commands collection and set its Voice property, you will typically also set its VoiceCaption property. This text will appear in the Voice Commands Window when your client application is input active. If this property is not set, the setting for the Caption property determines the text displayed. When neither the VoiceCaption or Caption property is set, the command does not appear in the Voice Commands Window.

IAgentUserInput

When the server notifies the input-active client with IAgentNotifySink::Command it 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 speech input triggers IAgentNotifySink::Command, the server returns the best match, the second-best match, and the third-best match, if these are provided by the speech engine. It provides the relative confidence scores, in the range of -100 to 100, and actual text "heard" by the speech engine. If the best match was a server-supplied command, the server sends a NULL ID, but still sends a confidence score and the Voice text.

If speech input was not the source for the event; 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.

Note Not all speech recognition engines may return all the values for all the parameters of this event. Check with your engine vendor to determine whether the engine supports the Microsoft Speech API interface for returning alternatives and confidence scores.

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).

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.

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.

IAgentBalloon

IAgentBalloon defines an interface that allows applications to query properties for the Microsoft Agent word balloon. These functions are also available from IAgentBalloonEx.

Initial defaults for a character's word balloon are set in the Microsoft Agent Character Editor, but once the application is running, the user may override the Enabled and Font properties. If a user changes the balloon's properties, the change affects all characters. The IAgentBalloon object's properties also apply to text output through the Think method.

Methods in Vtable Order

IAgentBalloon Methods	Description
GetEnabled	Returns whether the word balloon is enabled.
GetNumLines	Returns the number of lines displayed in the word balloon.
GetNumCharsPerLine	Returns the average number of characters per line displayed in the word balloon.
GetFontName	Returns the name of the font displayed in the word balloon.
GetFontSize	Returns the size of the font displayed in the word balloon.
GetFontBold	Returns whether the font displayed in the word balloon is bold.
GetFontItalic	Returns whether the font displayed in the word balloon is italic.
GetFontStrkethru	Returns whether the font displayed in the word balloon is displayed as strikethrough.
GetFontUnderline	Returns whether the font displayed in the word balloon is underlined.
GetForeColor	Returns the foreground color displayed in the word balloon.
GetBackColor	Returns the background color displayed in the word balloon.
GetBorderColor	Returns the border color displayed in the word balloon.
SetVisible	Sets the word balloon to be visible.
GetVisible	Returns the visibility setting for the word balloon.
SetFontName	Sets the font used in the word balloon.
SetFontSize	Sets the font size used in the word balloon.
SetFontCharSet	Sets the character set used in the word balloon.
GetFontCharSet	Returns the character set used in the word balloon.

IAgentBalloon::GetBackColor

HRESULT GetBackColor(
   long * plBGColor  // address of variable for background color displayed
);                   // in word balloon

Retrieves the value for the background color displayed in a word balloon.

Returns S_OK to indicate the operation was successful.

plBGColor

The address of a variable that receives the color setting for the balloon background.

The background color used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can change the background color of the word balloons for all characters through the Microsoft Agent property sheet.

See also IAgentBalloon::GetForeColor

IAgentBalloon::GetBorderColor

HRESULT GetBorderColor (
  long * plBorderColor// address of variable for border color displayed
);                    // for word balloon

Retrieves the value for the border color displayed for a word balloon.

Returns S_OK to indicate the operation was successful.

plBorderColor

The address of a variable that receives the color setting for the balloon border.

The border color for a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can change the border color of the word balloons for all characters through the Microsoft Agent property sheet.

IAgentBalloon::GetEnabled

HRESULT GetEnabled(
  long * pbEnabled  // address of variable for Enabled setting 
);                  // for word balloon

Retrieves the value of the Enabled property for a word balloon.

Returns S_OK to indicate the operation was successful.

pbEnabled

The address of a variable that receives True when the word balloon is enabled and False when it is disabled.

The Microsoft Agent server automatically displays the word balloon for spoken output, unless it is disabled. The word balloon can be disabled for a character in the Microsoft Agent Character Editor, or (by the user) for all characters in the Microsoft Agent property sheet. If the user disables the word balloon, the client cannot restore it.

IAgentBalloon::GetFontBold

HRESULT GetFontBold(
   long * pbFontBold  // address of variable for bold setting for
);                    // font displayed in word balloon

Indicates whether the font used in a word balloon is bold.

Returns S_OK to indicate the operation was successful.

pbFontBold

The address of a value that receives True if the font is bold and False if not bold.

The font style used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the font settings for all characters through the Microsoft Agent property sheet.

IAgentBalloon::GetFontCharSet

HRESULT GetFontCharSet(
   short * psFontCharSet  // character set displayed in word balloon
);

Indicates the character set of the font displayed in a word balloon.

Returns S_OK to indicate the operation was successful.

psFontCharSet

The address of a value that receives the font's character set. The following are some common settings for value:

0	Standard Windows characters (ANSI).
1	Default character set.
2	The symbol character set.
128	Double-byte character set (DBCS) unique to the Japanese version of Windows.
129	Double-byte character set (DBCS) unique to the Korean version of Windows.
134	Double-byte character set (DBCS) unique to the Simplified Chinese version of Windows.
136	Double-byte character set (DBCS) unique to the Traditional Chinese version of Windows.
255	Extended characters usually displayed by MS-DOSŽ applications.

For other character set values, consult the Microsoft Win32 documentation.

The default character set used in a character's word balloon is defined in the Microsoft Agent Character Editor. You can change it using IAgentBalloon::SetFontCharSet. However, the user can override the character set setting for all characters using the Microsoft Agent property sheet.

See also IAgentBalloon::SetFontCharSet

IAgentBalloon::GetFontItalic

HRESULT GetFontItalic(
   long * pbFontItalic  // address of variable for italic setting for 
);                      // font displayed in word balloon

Indicates whether the font used in a word balloon is italic.

Returns S_OK to indicate the operation was successful.

pbFontItalic

The address of a value that receives True if the font is italic and False if not italic.

The font style used in a character's word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the font settings for all characters through the Microsoft Agent property sheet.

IAgentBalloon::GetFontName

HRESULT GetFontName(
   BSTR * pbszFontName  // address of variable for font displayed 
);                      // in word balloon

Retrieves the value for the font displayed in a word balloon.

Returns S_OK to indicate the operation was successful.

pbszFontName

The address of a BSTR that receives the font name displayed in a word balloon.

The default font used in a character word balloon is defined in the Microsoft Agent Character Editor. You can change it with IAgentBalloon::SetFontName. The user can override the font setting for all characters using the Microsoft Agent property sheet.

IAgentBalloon::GetFontSize

HRESULT GetFontSize(
   long * plFontSize  // address of variable for font size 
);                    // for font displayed in word balloon

Retrieves the value for the size of the font displayed in a word balloon.

Returns S_OK to indicate the operation was successful.

plFontSize

The address of a value that receives the size of the font.

The default font size used in a character word balloon is defined in the Microsoft Agent Character Editor. You can change it with IAgentBalloon::SetFontSize. However, the user can override the font size settings for all characters using the Microsoft Agent property sheet.

IAgentBalloon::GetFontStrikethru

HRESULT GetFontStrikethru(
   long * pbFontStrikethru  // address of variable for strikethrough setting 
);                          // for font displayed in word balloon

Indicates whether the font used in a word balloon has the strikethrough style set.

Returns S_OK to indicate the operation was successful.

pbFontStrikethru

The address of a value that receives True if the font strikethrough style is set and False if not.

IAgentBalloon::GetFontUnderline

HRESULT GetFontUnderline(
   long * pbFontUnderline  // address of variable for underline setting
);                         // for font displayed in word balloon

Indicates whether the font used in a word balloon has the underline style set.

Returns S_OK to indicate the operation was successful.

pbFontUnderline

The address of a value that receives True if the font underline style is set and False if not.

IAgentBalloon::GetForeColor

HRESULT GetForeColor(
   long * plFGColor // address of variable for foreground color displayed
);                  // in word balloon

Retrieves the value for the foreground color displayed in a word balloon.

Returns S_OK to indicate the operation was successful.

plFGColor

The address of a variable that receives the color setting for the balloon foreground.

The foreground color used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the foreground color of the word balloons for all characters through the Microsoft Agent property sheet.

See also IAgentBalloon::GetBackColor

IAgentBalloon::GetNumCharsPerLine

HRESULT GetNumCharsPerLine(
   long * plCharsPerLine  // address of variable for characters per line
);                        // displayed in word balloon

Retrieves the value for the average number of characters per line displayed in a word balloon.

Returns S_OK to indicate the operation was successful.

The address of a variable that receives the number of characters per line.

The Microsoft Agent server automatically scrolls the lines displayed for spoken output in the word balloon. The average number of characters per line for a character's word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application.

IAgentBalloonEx

IAgentBalloonEx is derived from the IAgentBalloon interface. It includes all the IAgentBalloon methods and provides access to additional functions.

Methods in Vtable Order

IAgentBalloonEx Methods	Description
GetStyle	Returns the word balloon's output style.
SetStyle	Sets the word balloon's output style.
SetNumLines	Sets the number lines output in the word balloon.
SetNumCharsPerLine	Sets the number of characters per line output in the word balloon.

IAgentBalloonEx::GetStyle

HRESULT GetStyle(
   long * plStyle,  // address of style settings
);

Retrieves the character's word balloon style settings.

Returns S_OK to indicate the operation was successful.

plStyle

Style settings for the word balloon, which can be a combination of any of the following values:

const unsigned short BALLOON_STYLE_BALLOONON = 0x00000001;	The balloon is supported for output.
const unsigned short BALLOON_STYLE _SIZETOTEXT = 0x0000002;	The balloon height is sized to accommodate the text output.
const unsigned short BALLOON_STYLE _AUTOHIDE = 0x00000004;	The balloon is automatically hidden.
const unsigned short BALLOON_STYLE _AUTOPACE = 0x00000008;	The text output is paced based on the output rate.

When the BalloonOn style bit is set, the word balloon appears when the Speak or Think method is used, unless the user overrides its display through the Microsoft Agent property sheet. When not set, no balloon appears.

When the SizeToText style bit is set, the word balloon automatically sizes the height of the balloon to the current size of the text specified in the Speak or Think method. When not set, the balloon's height is based on the balloon's number of lines property setting. This style bit is set to 1 and an attempt to use IAgentBalloonEx::SetNumLines will result in an error.

When the AutoHide style bit is set, the word balloon automatically hides after a short time-out. When not set, the balloon displays until a new Speak or Think call, the character is hidden, or the user clicks or drags the character.

When the AutoPace style bit is set, the word balloon paces the output based on the current output rate, for example, one word at a time. When output exceeds the size of the balloon, the former text is automatically scrolled. When not set, all text included in a Speak or Think statement displays at once.

This property applies only to your client application's use of the character; the setting does not affect other clients of the character or other characters of your client application.

The defaults for these style bits are based on the settings when the character is compiled through the Microsoft Agent Character Editor.

IAgentCommandWindow

IAgentCommandWindow defines an interface that allows applications to set and query the properties of the Voice Commands Window. The Voice Commands Window is a shared resource primarily designed to enable users to view voice-enabled commands. If speech recognition is disabled, the Voice Commands Window still displays, with the text "Speech input disabled" (in the language of the character). If no speech engine is installed that matches the character's language setting, the window displays, "Speech input not available." If the input-active client has not defined voice parameters for its commands and has disabled global voice commands, the window displays, "No voice commands." You can also query the properties of the Voice Commands Window regardless of whether speech input is disabled or a compatible speech engine is installed.

Methods in Vtable Order

IAgentCommandWindow Methods	Description
SetVisible	Sets the value of the Visible property of the Voice Commands Window.
GetVisible	Returns the value of the Visible property of the Voice Commands Window.
GetPosition	Returns the position of the Voice Commands Window.
GetSize	Returns the size of the Voice Commands Window.

HRESULT GetPosition(
   long * plLeft,  // address of variable for left edge of Voice Commands Window
   long * plTop    // address of variable for top edge of Voice Commands Window
);

Retrieves the Voice Commands Window's position.

Returns S_OK to indicate the operation was successful.

plLeft

Address of a variable that receives the screen coordinate of the left edge of the Voice Commands Window in pixels, relative to the screen origin (upper left).

plTop

Address of a variable that receives the screen coordinate of the top edge of the Voice Commands Window in pixels, relative to the screen origin (upper left).

See also IAgentCommandWindow::GetSize

IAgentCommandWindow::GetSize

HRESULT GetSize(
   long * plWidth,  // address of variable for Voice Commands Window width
   long * plHeight  // address of variable for Voice Commands Window height
);

Retrieves the current size of the Voice Commands Window.

Returns S_OK to indicate the operation was successful.

plWidth

Address of a variable that receives the width of the Voice Commands Window in pixels, relative to the screen origin (upper left).

plHeight

Address of a variable that receives the height of the Voice Commands Window in pixels, relative to the screen origin (upper left).

IAgentCommandWindow::GetVisible

HRESULT GetVisible(
   long * pbVisible  // address of variable for Visible setting for 
);                   // Voice Commands Window

Determines whether the Voice Commands Window is visible or hidden.

Returns S_OK to indicate the operation was successful.

pbVisible

Address of a variable that receives True if the Voice Commands Window is visible, or False if hidden.

IAgentCommandWindow::SetVisible

HRESULT SetVisible(
   long bVisible  // Voice Commands Window Visible setting 
);

Set the Visible property for the Voice Commands Window.

Returns S_OK to indicate the operation was successful.

bVisible

Visible property setting. A value of True displays the Voice Commands Window; False hides it.

The user can override this property.

IAgentSpeechInputProperties

IAgentSpeechInputProperties provides access to the speech input properties maintained by the server. Most of the properties are read-only for client applications, but the user can change them in the Microsoft Agent property sheet. The Microsoft Agent server returns values only if a compatible speech engine has been installed and is enabled. Querying these properties attempts to start the speech engine.

Methods in Vtable Order

IAgentSpeechInputProperties Methods	Description
GetEnabled	Returns whether the speech recognition engine is enabled.
GetHotKey	Returns the current key assignment of the Listening key.
GetListeningTip	Returns whether the Listening Tip is enabled.

GetInstalled, GetLCID, GetEngine, and SetEngine methods (supported in earlier versions of Microsoft Agent) are still supported for backward compatibility. However, the methods are not stubbed and do not return useful values. Use GetSRModeID and SetSRModeID to query and set the speech recognition engine to be used with the character. Keep in mind that the engine must match the character's current language setting.

IAgentSpeechInputProperties::GetEnabled

HRESULT GetEnabled(
   long * pbEnabled  // address of variable for speech recognition engine 
);                   // Enabled setting

Retrieves a value indicating whether the installed speech recognition engine is enabled.

Returns S_OK to indicate the operation was successful.

pbEnabled

Address of a variable that receives True if the speech engine is currently enabled and False if disabled.

IAgentSpeechInputProperties::GetHotKey

HRESULT GetHotKey(
BSTR * pbszHotCharKey  // address of variable for listening key 
);

Retrieves the current keyboard assignment for the speech input Listening key.

Returns S_OK to indicate the operation was successful.

pbszHotCharKey

Address of a BSTR that receives the current hotkey setting used to open the audio channel for speech input.

If GetEnabled returns False, querying this setting raises an error.

IAgentSpeechInputProperties::GetListeningTip

HRESULT GetListeningTip(
long * pbListeningTip  // address of variable for listening tip flag
);

Retrieves a value indicating whether the Listening Tip is enabled for display.

Returns S_OK to indicate the operation was successful.

pbListeningTip

Address of a variable that receives True if the Listening Tip is enabled for display, or False if the Listening Tip is disabled.

If GetEnabled returns False, querying any other speech input properties returns an error.

IAgentAudioOutputProperties

IAgentAudioOutputProperties provides access to audio output properties maintained by the Microsoft Agent server. These functions are also available from IAgentAudioOutputPropertiesEx. The properties are read-only, but the user can change them in the Microsoft Agent property sheet.

Methods in Vtable Order

IAgentAudioOutputProperties Methods	Description
GetEnabled	Returns whether audio output is enabled.
GetUsingSoundEffects	Returns whether sound-effect output is enabled.

IAgentAudioOutputProperties::GetEnabled

HRESULT GetEnabled(
long * pbEnabled  // address of variable for audio output Enabled setting 
);

Retrieves a value indicating whether character speech output is enabled.

Returns S_OK to indicate the operation was successful.

pbEnabled

Address of a variable that receives True if the speech output is currently enabled and False if disabled.

Because this setting affects spoken output (TTS and sound file) for all characters, only the user can change this property in the Microsoft Agent property sheet.

IAgentAudioOutputProperties

HRESULT GetUsingSoundEffects(
long * pbUsingSoundEffects  // address of variable sound effects output 
);                          // setting

Retrieves a value indicating whether sound effects output is enabled.

Returns S_OK to indicate the operation was successful.

pbUsingSoundEffects

Address of a variable that receives True if the sound effects output is currently enabled and False if disabled.

Sound effects for a character's animation are assigned in the Microsoft Agent Character Editor. Because this setting affects sound effects output for all characters, only the user can change this property in the Microsoft Agent property sheet.

IAgentAudioOutputPropertiesEx

IAgentAudioOutputPropertiesEx is derived from the IAgentAudioOutputProperties interface. It includes all the IAgentAudioOutputProperties methods and provides access to additional functions.

Methods in Vtable Order

IAgentAudioOutputPropertiesEx Methods	Description
GetStatus	Returns the status of the audio output channel.

IAgentAudioOutputPropertiesEx::GetStatus

HRESULT GetStatus(
   long * plStatus,  // address of audio channel status
);

Retrieves the status of the audio channel.

Returns S_OK to indicate the operation was successful.

plStatus

Status of the audio output channel, which may be one of the following values:

const unsigned short AUDIO_STATUS_AVAILABLE = 0;	The audio output channel is available (not busy).
const unsigned short AUDIO_STATUS_NOAUDIO = 1;	There is no support for audio output; for example, because there is no sound card.
const unsigned short AUDIO_STATUS_CANTOPENAUDIO = 2;	The audio output channel can't be opened (is busy); for example, because another application is playing audio.
const unsigned short AUDIO_STATUS_USERSPEAKING = 3;	The audio output channel is busy because the server is processing user speech input
const unsigned short AUDIO_STATUS_CHARACTERSPEAKING = 4;	The audio output channel is busy because a character is currently speaking.
const unsigned short AUDIO_STATUS_SROVERRIDEABLE = 5;	The audio output channel is not busy, but it is waiting for user speech input.
const unsigned short AUDIO_STATUS_ERROR = 6;	There was some other (unknown) problem in attempting to access the audio output channel.

This setting enables your client application to query the state of the audio output channel. You can use this to determine whether to have your character speak or to try to turn on Listening mode (using IAgentCharacterEx::Listen).

IAgentPropertySheet

IAgentPropertySheet defines an interface that allows applications to set and query p/P>

Methods in Vtable Order

IAgentPropertySheet Methods	Description
GetVisible	Returns whether the Microsoft Agent property sheet is visible.
SetVisible	Sets the Visible property of the Microsoft Agent property sheet.
GetPosition	Returns the position of the Microsoft Agent property sheet.
GetSize	Returns the size of the Microsoft Agent property sheet.
GetPage	Returns the current page for the Microsoft Agent property sheet.
SetPage	Sets the current page for the Microsoft Agent property sheet.

IAgentPropertySheet::GetPage

HRESULT GetPage(
BSTR * pbszPage  // address of variable for current property page
);

Retrieves the current page of the Microsoft Agent property sheet.

Returns S_OK to indicate the operation was successful.

pbszPage

Address of a variable that receives the current page of the property sheet (last viewed page if the window is not open). The parameter can be one of the following:

"Speech"	The Speech Input page.
"Output"	The Output page.
"Copyright"	The Copyright page.

See also IAgentPropertySheet::SetPage

IAgentPropertySheet::GetPosition

HRESULT GetPosition(
   long * plLeft,  // address of variable for left edge of property sheet
   long * plTop    // address of variable for top edge of property sheet
);

Retrieves the Microsoft Agent's property sheet window position.

Returns S_OK to indicate the operation was successful.

plLeft

Address of a variable that receives the screen coordinate of the left edge of the property sheet in pixels, relative to the screen origin (upper left).

plTop

Address of a variable that receives the screen coordinate of the top edge of the property sheet in pixels, relative to the screen origin (upper left).

See also IAgentPropertySheet::GetSize

IAgentPropertySheet::GetSize

HRESULT GetSize(
   long * plWidth,  // address of variable for property sheet width
   long * plHeight  // address of variable for property sheet height
);

Retrieves the size of the Microsoft Agent property sheet window.

Returns S_OK to indicate the operation was successful.

plWidth

Address of a variable that receives the width of the property sheet in pixels, relative to the screen origin (upper left).

plHeight

Address of a variable that receives the height of the property sheet in pixels, relative to the screen origin (upper left).

IAgentPropertySheet::GetVisible

HRESULT GetVisible(
   long * pbVisible  // address of variable for property sheet
);                   // Visible setting

Determines whether the Microsoft Agent property sheet is visible or hidden.

Returns S_OK to indicate the operation was successful.

pbVisible

Address of a variable that receives True if the property sheet is visible and False if hidden.

IAgentPropertySheet::SetPage

HRESULT SetPage(
   BSTR bszPage  // current property page
);

Sets the current page of the Microsoft Agent property sheet.

Returns S_OK to indicate the operation was successful.

bszPage

A BSTR that sets the current page of the property. The parameter can be one of the following.

"Speech"	The Speech Input page.
"Output"	The Output page.
"Copyright"	The Copyright page.

See also IAgentPropertySheet::GetPage

IAgentPropertySheet::SetVisible

HRESULT SetVisible(
   long bVisible  // property sheet Visible setting 
);

Sets the Visible property for the Microsoft Agent property sheet.

Returns S_OK to indicate the operation was successful.

bVisible

Visible property setting. A value of True displays the property sheet; a value of False hides it.

Events

IAgentNotifySink notifies clients when certain state changes occur. These functions are also available from IAgentNotifySinkEx.

Methods in Vtable Order

IAgentNotifySink	Description
Command	Occurs when the server processes a client-defined command.
ActivateInputState	Occurs when a character becomes or ceases to be input-active.
VisibleState	Occurs when the character's Visible state changes.
Click	Occurs when a character is clicked.
DblClick	Occurs when a character is double-clicked.
DragStart	Occurs when a user starts dragging a character.
DragComplete	Occurs when a user stops dragging a character.
RequestStart	Occurs when the server begins processing a Request object.
RequestComplete	Occurs when the server completes processing a Request object.
Bookmark	Occurs when the server processes a bookmark.
Idle	Occurs when the server starts or ends idle processing.
Move	Occurs when a character has been moved.
Size	Occurs when a character has been resized.
BalloonVisibleState	Occurs when the visibility state of a character's word balloon changes.

The IAgentNotifySink::Restart and IAgentNotifySink::Shutdown events, supported in earlier versions of Microsoft Agent, are now obsolete. While supported for backward compatibility, the server no longer sends these events.

IAgentNotifySink::ActivateInputState

HRESULT ActivateInputState(
   long dwCharID,   // character ID
   long bActivated  // input activation flag
);

Notifies a client application that a character's input active state changed.

No return value.

dwCharID

Identifier of the character whose input activation state changed.

bActivated

Input active flag. This Boolean value is True if the character referred to by dwCharID became input active; and False if the character lost its input active state.

IAgentNotifySink:: BalloonVisibleState

HRESULT BalloonVisibleState(
   long dwCharID,  // character ID
   long bVisible   // visibility flag
);

Notifies a client application when the visibility state of the character's word balloon changes.

No return value.

dwCharID

Identifier of the character whose word balloon's visibility state has changed.

bVisible

Visibility flag. This Boolean value is True when character's word balloon becomes visible; and False when it becomes hidden.

This event is sent to all clients of the character.

IAgentNotifySink::Bookmark

HRESULT Bookmark(
   long dwBookMarkID  // bookmark ID
);

Notifies a client application when its bookmark completes.

No return value.

dwBookMarkID

Identifier of the bookmark that resulted in triggering the event.

When you include bookmark tags in a Speak method, you can track when they occur with this event.

IAgentNotifySink::Click

HRESULT Click(
   long dwCharID,  // character ID
   short fwKeys,   // mouse button and modifier key state
   long x,         // x coordinate of mouse pointer
   long y          // y coordinate of mouse pointer
);

Notifies a client application when the user clicks a character or character's taskbar icon.

No return value.

dwCharID

Identifier of the clicked character.

fwKeys

A parameter that indicates the mouse button and modifier key state. The parameter can return any combination of the following:

0x0001	Left Button
0x0010	Middle Button
0x0002	Right Button
0x0004	Shift Key Down
0x0008	Control Key Down
0x0020	Alt Key Down
0x1000	Event occurred on the character's taskbar icon

The x-coordinate of the mouse pointer in pixels, relative to the screen origin (upper left).

The y-coordinate of the mouse pointer in pixels, relative to the screen origin (upper left).

This event is sent to the input-active client of the character. If none of the character's clients are input-active, the server notifies the character's active client. If the character is visible, the server also makes that client input-active and sends the IAgentNotifySink::ActivateInputState. If the character hidden, the character is also automatically shown.

IAgentNotifySink::Command

HRESULT Command(
   long dwCommandID,         // Command ID of the best match
   IUnknown * punkUserInput  // address of IAgentUserInput object 
);

Notifies a client application that a Command was selected by the user.

No return value.

dwCommandID

Identifier of the best match command alternative.

punkUserInput

Address of the IUnknown interface for the IAgentUserInput object.

Use QueryInterface to retrieve the IAgentUserInput interface.

The server notifies the input-active client when the user chooses a command by voice or by selecting a command from the character's pop-up menu. The event occurs even when the user selects one of the server's commands. In this case the server returns a null command ID, the confidence score, and the voice text returned by the speech engine for that entry.

IAgentNotifySinkEx

IAgentNotifySinkEx is derived from the IAgentNotifySink interface. It includes all the IAgentNotifySink methods and provides access to additional functions.

Methods in Vtable Order

IAgentNotifySinkEx Methods	Description
HelpComplete	Occurs when the user selects a menu or the character in Help mode.
ListeningState	Occurs when the character's listening state changes.
Suspend	Occurs when the server suspends operation.
DefaultCharacterChange	Occurs when the user changes the default character.
AgentPropertyChange	Occurs when the user changes an Agent property setting.
ActiveClientChange	Occurs when the active client of a character changes.

IAgentNotifySinkEx::ActiveClientChange

HRESULT ActiveClientChange(
...long dwCharID,  // character ID
   long lStatus    // active state flag
);

Notifies a client application if its active client is no longer the active client of a character.

No return value.

dwCharID

Identifier of the character for which active client status changed.

lStatus

Active state change of the client, which can be a combination of any of the following values:

const unsigned short ACTIVATE_NOTACTIVE = 0;	Your client is not the active client of the character.
const unsigned short ACTIVATE_ACTIVE = 1;	Your client is the active client of the character.
const unsigned short ACTIVATE_INPUTACTIVE = 2;	Your client is input-active (active client of the topmost character).

When multiple client applications share the same character, the active client of the character receives mouse input (for example, Microsoft Agent control click or drag events). Similarly, when multiple characters are displayed, the active client of the topmost character (also known as the input-active client) receives IAgentNotifySink::Command events.

When the active client of a character changes, this event passes back the ID of that character and True if your application has become the active client of the character or False if it is no longer the active client of the character.

A client application may receive this event when the user selects another client application's entry in character's pop-up menu or by voice command, the client application changes its active status, or another client application quits its connection to Microsoft Agent. Agent sends this event only to the client applications that are directly affected -- those that either become the active client or stop being the active client.

You can use the Activate method to set whether your application is the active client of the character or to make your application the input-active client (which also makes the character topmost).

IAgentNotifySinkEx::AgentPropertyChange

HRESULT AgentPropertyChange(
);

Notifies a client application when the user changes a Microsoft Agent property setting.

No return value.

When the user changes a Microsoft Agent property setting in the Microsoft Agent property sheet, the server sends this event to all clients unless the server is currently suspended.

IAgentNotifySinkEx::DefaultCharacterChange

HRESULT DefaultCharacterChange(
   BSTR bszGUID  // character identifier
);

Notifies a client application when the default character changes.

No return value.

bszGUID

The unique identifier for the character.

When the user changes the character assigned as the user's default character, the server sends this event to clients that have loaded the default character. The event returns the character's unique identifier (GUID) formatted with braces and dashes, which is defined when the character is built with the Microsoft Agent Character Editor.

When the new character appears, it assumes the same size as any already loaded instance of the character or the previous default character (in that order).

const unsigned short NeverMoved = 0;	Character has not been moved.
const unsigned short UserMoved = 1;	User dragged the character.
const unsigned short ProgramMoved = 2;	Your application moved the character.
const unsigned short OtherProgramMoved = 3;	Another application moved the character.
const unsigned short SystemMoved = 4	The server moved the character to keep it onscreen after a screen resolution change.

const unsigned short NeverShown = 0;	Character has not been shown.
const unsigned short UserHid = 1;	User hid the character with the character's taskbar icon pop-up menu or using speech input.
const unsigned short UserShowed = 2;	User showed the character.
const unsigned short ProgramHid = 3;	Your application hid the character.
const unsigned short ProgramShowed = 4;	Your application showed the character.
const unsigned short OtherProgramHid = 5;	Another application hid the character.
const unsigned short OtherProgramShowed = 6;	Another application showed the character.
const unsigned short UserHidViaCharacterMenu = 7	User hid the character with the character's pop-up menu.
const unsigned short UserHidViaTaskbarIcon = UserHid	User hid the character with the character's taskbar icon pop-up menu or using speech input.

const unsigned short PREPARE_ANIMATION = 0;	A character's animation data.
const unsigned short PREPARE_STATE = 1;	A character's state data.
const unsigned short PREPARE_WAVE = 2	A character's sound file (.WAV or .LWV) for spoken output.

"Gesturing"	To retrieve all Gesturing state animations.
"GesturingDown"	To retrieve GesturingDown animations.
"GesturingLeft"	To retrieve GesturingLeft animations.
"GesturingRight"	To retrieve GesturingRight animations.
"GesturingUp"	To retrieve GesturingUp animations.
"Hiding"	To retrieve the Hiding state animations.
"Hearing"	To retrieve the Hearing state animations.
"Idling"	To retrieve all Idling state animations.
"IdlingLevel1"	To retrieve all IdlingLevel1 animations.
"IdlingLevel2"	To retrieve all IdlingLevel2 animations.
"IdlingLevel3"	To retrieve all IdlingLevel3 animations.
"Listening"	To retrieve the Listening state animations.
"Moving"	To retrieve all Moving state animations.
"MovingDown"	To retrieve all Moving animations.
"MovingLeft"	To retrieve all MovingLeft animations.
"MovingRight"	To retrieve all MovingRight animations.
"MovingUp"	To retrieve all MovingUp animations.
"Showing"	To retrieve the Showing state animations.
"Speaking"	To retrieve the Speaking state animations.

const unsigned long STOP_TYPE_ALL = 0xFFFFFFFF;	Stops all animation requests, including non-queued Prepare requests.
const unsigned long STOP_TYPE_PLAY = 0x00000001;	Stops all Play requests.
const unsigned long STOP_TYPE_MOVE = 0x00000002;	Stops all Move requests.
const unsigned long STOP_TYPE_SPEAK = 0x00000004;	Stops all Speak requests.
const unsigned long STOP_TYPE_PREPARE = 0x00000008;	Stops all queued Prepare requests.
const unsigned long STOP_TYPE_NONQUEUEDPREPARE = 0x00000010;	Stops all non-queued Prepare requests.
const unsigned long STOP_TYPE_VISIBLE = 0x00000020;	Stops all Hide or Show requests.

0	Set as not the active client.
1	Set as the active client.
2	Make the topmost character.

const unsigned long LISTEN_STATUS_CANLISTEN = 0;	Conditions support speech input.
const unsigned long LISTEN_STATUS_NOAUDIO = 1;	There is no audio input device available on this system. (Note that this does not detect whether a microphone is installed; it can only detect whether the user has a properly installed input-enabled sound card with a working driver.)
const unsigned long LISTEN_STATUS_NOTTOPMOST = 2;	Another client is the active client of this character, or the current character is not topmost.
const unsigned long LISTEN_STATUS_CANTOPENAUDIO = 3;	The audio input or output channel is currently busy, some other application is using audio.
const unsigned long LISTEN_STATUS_COULDNTINITIALIZESPEECH = 4;	An unspecified error occurred in the process of initializing the speech recognition subsystem. This includes the possibility that there is no speech engine available matching the character's language setting.
const unsigned long LISTEN_STATUS_SPEECHDISABLED = 5;	The user has disabled speech input in the Advanced Character Options window.
const unsigned long LISTEN_STATUS_ERROR = 6;	An error occurred in checking the audio status, but the cause of the error was not returned by the system.

const unsigned short CSHELPCAUSE_COMMAND = 1;	The user selected a command supplied by your application.
const unsigned short CSHELPCAUSE_OTHERPROGRAM = 2;	The user selected the Commands object of another client.
const unsigned short CSHELPCAUSE_OPENCOMMANDSWINDOW = 3;	The user selected the Open Voice Commands command.
const unsigned short CSHELPCAUSE_CLOSECOMMANDSWINDOW = 4;	The user selected the Close Voice Commands command.
const unsigned short CSHELPCAUSE_SHOWCHARACTER = 5;	The user selected the Show CharacterName command.
const unsigned short CSHELPCAUSE_HIDECHARACTER = 6;	The user selected the Hide CharacterName command.
const unsigned short CSHELPCAUSE_CHARACTER = 7;	The user selected (clicked) the character.

const unsigned long LSCOMPLETE_CAUSE_PROGRAMDISABLED = 1;	Listening mode was turned off by program code.
const unsigned long LSCOMPLETE_CAUSE_PROGRAMTIMEDOUT = 2;	Listening mode (turned on by program code) timed out.
const unsigned long LSCOMPLETE_CAUSE_USERTIMEDOUT = 3;	Listening mode (turned on by the Listening key) timed out.
const unsigned long LSCOMPLETE_CAUSE_USERRELEASEDKEY = 4;	Listening mode was turned off because the user released the Listening key.
const unsigned long LSCOMPLETE_CAUSE_USERUTTERANCEENDED = 5;	Listening mode was turned off because the user finished speaking.
const unsigned long LSCOMPLETE_CAUSE_CLIENTDEACTIVATED = 6;	Listening mode was turned off because the input active client was deactivated.
const unsigned long LSCOMPLETE_CAUSE_DEFAULTCHARCHANGE = 7	Listening mode was turned off because the default character was changed.
const unsigned long LSCOMPLETE_CAUSE_USERDISABLED = 8	Listening mode was turned off because the user disabled speech input.