IAgentCharacter

IAgentCharacter defines an interface that allows applications to query character properties and play animations.

Methods in Vtable Order

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:

0Set as not the active client.

1Set as the active client.

2Make 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.

If you call this method to a function, it returns a Boolean value that indicates whether the method succeeded. 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 because a character must always have a topmost client.

See also IAgentCharacter::HasOtherClients

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.

x

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

y

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.

See also IAgentCharacter::SetIdleOn

IAgentCharacter::GetMoveCause

HRESULT GetMoveCause(
   long * pdwCause  // address of variable for cause of character move
);

Retrieves the cause of the character's last move.

• Returns S_OK to indicate the operation was successful.

pdwCause

Address of a variable that receives the cause of the character's last move and will be one of the following:

See also IAgentNotifySink::Move

IAgentCharacter::GetName

HRESULT GetName(
   BSTR * pbszName   // address of buffer for character name
);

Retrieves the name of the character.

• Returns S_OK to indicate the operation was successful.

pbszName

The address of a BSTR that receives the value of the name for the character. A character's default name is defined when it is compiled with the Microsoft Agent Character Editor. The name setting is optional and may not be supported for all characters. You can also set the character's name using IAgentCharacter:SetName; however, this changes the name for all current clients of the character.

See also IAgentCharacter::SetName

IAgentCharacter::GetPosition

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

Retrieves the character's animation frame position.

• Returns S_OK to indicate the operation was successful.

plLeft

Address of a variable that receives the screen coordinate of the character animation frame's left edge in pixels, relative to the screen origin (upper left).

plTop

Address of a variable that receives the screen coordinate of the character animation frame's top edge in pixels, relative to the screen origin (upper left).

Even though the character appears in an irregularly shaped region window, the location of the character is based on its rectangular animation frame.

See also IAgentCharacter::SetPosition, IAgentCharacter::GetSize

IAgentCharacter::GetSize

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

Retrieves the size of the character's animation frame.

• Returns S_OK to indicate the operation was successful.

plWidth

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

plHeight

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

Even though the character appears in an irregularly shaped region window, the location of the character is based on its rectangular animation frame.

See also IAgent::SetSize

IAgentCharacter::GetSoundEffectsOn

HRESULT GetSoundEffectsOn(
   long * pbOn  // address of variable for sound effects setting 
);

Retrieves whether the character's sound effects setting is enabled.

• Returns S_OK to indicate the operation was successful.

pbOn

Address of a variable that receives TRUE if the character's sound effects setting is enabled, FALSE if disabled.

The character's sound effects setting determines whether sound effects compiled as a part of the character are played when you play an associated animation. The setting is subject to the user's global sound effects setting in IAgentAudioOutputProperties::GetUsingSoundEffects.

See also IAgentCharacter::SetSoundEffectsOn, IAgentAudioOutputProperties::GetUsingSoundEffects

IAgentCharacter::GetTTSPitch

HRESULT GetTTSPitch(
   long * pdwPitch  // address of variable for character TTS pitch
);

Retrieves the character's TTS output pitch setting.

• Returns S_OK to indicate the operation was successful.

pdwPitch

Address of a variable that receives the character's current TTS pitch setting in Hertz.

Although your application cannot write this value, you can include pitch tags in your output text that will temporarily increase the pitch for a particular utterance. This method applies only to characters configured for TTS output. If the speech synthesis (TTS) engine is not enabled (or installed) or the character does not support TTS output, this method returns zero (0).

IAgentCharacter::GetTTSSpeed

HRESULT GetTTSSpeed(
   long * pdwSpeed  // address of variable for character TTS output speed
);

Retrieves the character's TTS output speed setting.

• Returns S_OK to indicate the operation was successful.

pdwSpeed

Address of a variable that receives the output speed of the character in words per minute.

Although your application cannot write this value, you can include speed tags in your output text that will temporarily speed up the output for a particular utterance.

This property returns the current speaking output speed setting for the character. For characters using TTS output, the property returns the actual TTS output for the character. If TTS is not enabled or the character does not support TTS output, the setting reflects the user setting for output speed.

IAgentCharacter::GetVisibilityCause

HRESULT GetVisibilityCause(
   long * pdwCause  // address of variable for cause of character visible state
);

Retrieves the cause of the character's visible state.

• Returns S_OK to indicate the operation was successful.

pdwCause

Address of a variable that receives the cause of the character's last visibility state change and will be one of the following:

See also IAgentNotifySink::Hide, IAgentNotifySink::Show

IAgentCharacter::GetVisible

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

Determines whether the character's animation frame is currently visible.

• Returns S_OK to indicate the operation was successful.

pbVisible

Address of a variable that receives TRUE if the character's frame is visible and FALSE if hidden.

You can use this method to determine whether the character's frame is currently visible. To make a character visible, use the Show method. To hide a character, use the Hide method.

IAgentCharacter::HasOtherClients

HRESULT HasOtherClients(
   long * pbHasOtherClients  // address of variable for whether character has
);                           // other clients

Retrieves whether a character has other clients.

• Returns S_OK to indicate the operation was successful.

pbHasOtherClients

Address of a variable that receives TRUE if the character has other clients and FALSE if not.

IAgentCharacter::Hide

HRESULT Hide(
   long bFast,      // play Hiding state animation flag
   long * pdwReqID  // address of request ID
);

Hides the character.

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

bFast

Hiding state animation flag. If this parameter is TRUE, the Hiding animation does not play before the character frame is hidden; if FALSE, the animation plays.

pdwReqID

Address of a variable that receives the Hide request ID.

The server queues the animation associated with the Hide method in the character's queue. This allows you to use it to hide the character after a sequence of other animations. You can play the action immediately by using the Stop method before calling the Hide method.

When using the HTTP protocol to access character and animation data, use the Prepare method to ensure the availability of the Hiding state animation before calling this method.

Hiding a character can also result in triggering the ActivateInput event of another visible character.

Hidden characters cannot access the audio channel. The server will pass back a failure status in the RequestComplete event if you generate an animation request and the character is hidden.

See also IAgentCharacter::Show

IAgentCharacter::Interrupt

HRESULT Interrupt(
   long dwReqID,    // request ID to interrupt
   long * pdwReqID  // address of request ID
);

Interrupts the specified animation (request) of another character.

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

dwReqID

An ID of the request to interrupt.

pdwReqID

Address of a variable that receives the Interrupt request ID.

You can use this method to sync up animation between characters. For example, if another character is in a looping animation, this method will stop the looping animation and start the next animation in the character's queue.

Interrupt halts the existing animation, but does not flush the character's animation queue. It starts the next animation in the character's queue. To halt and flush a character's queue, use the Stop method.

You cannot use this method to have a character interrupt itself because the Microsoft Agent server queues the Interrupt method in the character's animation queue. Therefore, you can only use Interrupt to halt the animation of another character you have loaded.

IAgentCharacter::MoveTo

HRESULT MoveTo(
   short x,         // x-coordinate of new location
   short y,         // y-coordinate of new location
   long lSpeed,     // speed to move the character
   long * pdwReqID  // address of request ID
);

Plays the associated Moving state animation and moves the character frame to the specified location.

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

x

The x-coordinate of the new position in pixels, relative to the screen origin (upper left). The location of a character is based on the upper left corner of its animation frame.

y

The y-coordinate of the new position in pixels, relative to the screen origin (upper left). The location of a character is based on the upper left corner of its animation frame.

lSpeed

A parameter specifying in milliseconds how quickly the character's frame moves. The recommended value is 1000. Specifying zero (0) moves the frame without playing an animation.

pdwReqID

Address of a variable that receives the MoveTo request ID.

When using the HTTP protocol to access character and animation data, use the Prepare method to ensure the availability of the Moving state animations before calling this method. Even if the animation is not loaded, the server still moves the frame.

See also IAgentCharacter::SetPosition

IAgentCharacter::Play

HRESULT Play(
   BSTR bszAnimation,  // name of an animation
   long * pdwReqID     // address of request ID
);

Plays the specified animation.

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

bszAnimation

The name of an animation.

pdwReqID

Address of a variable that receives the Play request ID.

An animation's name is defined when the character is compiled with the Microsoft Agent Character Editor. Before playing the specified animation, the server attempts to play the Return animation for the previous animation (if one has been assigned).

When a character's animation data is stored on the user's local machine, you can use the Play method and specify the name of the animation. When using the HTTP protocol to access animation data, use the Prepare method to ensure the availability of the animation before calling this method.

See also IAgentCharacter::Prepare

IAgentCharacter::Prepare

HRESULT Prepare(
   long dwType,     // type of animation data to load
   BSTR bszName,    // name of the animation 
   long bQueue,     // queue the request
   long * pdwReqID  // address of request ID
);

Retrieves animation data for a character.

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

dwType

A value that indicates the animation data type to load that must be one of the following:

bszName

The name of the animation or state.

The animation name is based on that defined for the character when it was saved using the Microsoft Agent Character Editor.

For states, the value can be one of the following:

For .WAV files, set bszName to the URL or file specification for the .WAV file. If the specification is not complete, it is interpreted as being relative to the specification used in the Load method.

bQueue

A Boolean specifying whether the server queues the Prepare request. TRUE queues the request and causes any animation request that follows it to wait until the animation data it specifies is loaded. FALSE retrieves the animation data asynchronously.

pdwReqID

Address of a variable that receives the Prepare request ID.

You can specify multiple animations and states by separating them with commas. However, you cannot mix types in the same Prepare statement.

IAgentCharacter::SetDescription

HRESULT SetDescription(
   BSTR bszDescription   // character description
); 

Sets the description of the character.

• Returns S_OK to indicate the operation was successful.

bszDescription

A BSTR that sets the description for the character. A character's default 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. You can change the character's description using IAgentCharacter::SetDescription; however, this value is not persistent (stored permanently). The character's description reverts to its default setting whenever the character is first loaded by a client.

See also IAgentCharacter::GetDescription

IAgentCharacter::SetIdleOn

HRESULT SetIdleOn(
   long bOn  // idle processing flag
);

Sets automatic idle processing for a character.

• Returns S_OK to indicate the operation was successful.

bOn

Idle processing flag. If this parameter is TRUE, the Microsoft Agent automatically plays Idling state animations.

The server automatically sets a time out after the last animation played for a character. When this timer's interval is complete, the server begins the Idling states for a character, playing its associated Idling animations at regular intervals. If you want to manage the Idling state animations yourself, set the property to FALSE.

See also IAgentCharacter::GetIdleOn

IAgentCharacter::SetName

HRESULT SetName(
   BSTR bszName   // character name
);

Sets the name of the character.

• Returns S_OK to indicate the operation was successful.

bszName

A BSTR that sets the character's name. A character's default name is defined when it is compiled with the Microsoft Agent Character Editor. You can change it using IAgentCharacter::SetName; however, this changes the character name for all current clients of the character. This property is not persistent (stored permanently). The character's name reverts to its default name whenever the character is first loaded by a client.

The server uses the character's name setting in parts of the Microsoft Agent's interface, such as the Commands Window title when the character is input-active and in the Microsoft Agent taskbar pop-up menu.

See also IAgentCharacter::GetName

IAgentCharacter::SetPosition

HRESULT SetPosition(
   long lLeft,  // screen coordinate of the left edge of character 
   long lTop    // screen coordinate of the top edge of character 
);

Sets the position of the character's animation frame.

• Returns S_OK to indicate the operation was successful.

lLeft

Screen coordinate of the character animation frame's left edge in pixels, relative to the screen origin (upper left).

lTop

Screen coordinate of the character animation frame's top edge in pixels, relative to the screen origin (upper left).

Even though the character appears in an irregularly shaped region window, the location of the character is based on its rectangular animation frame.

NoteUnlike the MoveTo method, this function is not queued.

See also IAgent::GetPosition

IAgentCharacter::SetSize

HRESULT SetSize(
   long * lWidth,  // width of the character frame
   long * lHeight  // height of the character frame
);

Sets the size of the character's animation frame.

• Returns S_OK to indicate the operation was successful.

lWidth

The width of the character's animation frame in pixels.

lHeight

The height of the character's animation frame in pixels.

Changing the character's frame size scales the character to the size set with this method.

Even though the character appears in an irregularly shaped region window, the location of the character is based on its rectangular animation frame.

See also IAgentCharacter::GetSize

IAgentCharacter::SetSoundEffectsOn

HRESULT SetSoundEffectsOn(
   long bOn  // character sound effects setting 
);

Determines whether the character's sound effects are played.

• Returns S_OK to indicate the operation was successful.

bOn

Sound effects setting. If this parameter is TRUE, the sound effects for animations are played when the animation plays; if FALSE, sound effects are not played.

This setting determines whether sound effects compiled as a part of the character are played when you play an associated animation. The setting is subject to the user's global sound effects setting in IAgentAudioOutputProperties::GetUsingSoundEffects.

See also IAgentCharacter::GetSoundEffectsOn, IAgentAudioOutputProperties::GetUsingSoundEffects

IAgentCharacter::Show

HRESULT Show(
   long bFast,      // play Showing state animation flag
   long * pdwReqID  // address of request ID
);

Displays a character.

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

bFast

Showing state animation flag. If this parameter is TRUE, the Showing state animation plays after making the character visible; if FALSE, the animation does not play.

pdwReqID

Address of a variable that receives the Show request ID.

Avoid setting the bFast parameter to TRUE without playing an animation beforehand, otherwise, the character frame may be displayed, but have no image to display. In particular, note that that if you call MoveTo when the character is not visible, it does not play any animation. Therefore, if you call the Show method with bFast set to TRUE, no image will be displayed. Similarly, if you call Hide then Show with bFast set to TRUE, there will be no visible image.

When using the HTTP protocol to access character and animation data, use the Prepare method to ensure the availability of the Showing state animation before calling this method.

See also IAgentCharacter::Hide

IAgentCharacter::Speak

HRESULT Speak(
   BSTR bszText,    // text to speak
   BSTR bszURL,     // URL of a file to speak
   long * pdwReqID  // address of a request ID
);

Speaks the

• Returns S_OK to indicate the operation was successful.

bszText

The text the character is to speak.

bszURL

The URL (or file specification) of a sound file to use for spoken output. This can be a standard sound file (.WAV) or linguistically enhanced sound file (.LWV).

pdwReqID

Address of a variable that receives the Speak request ID.

To use this method with a character configured to speak using a text-to-speech (TTS) engine; simply provide the bszText parameter. You can include vertical bar characters (|) in the bszText parameter to designate alternative strings, so that each time the server processes the method, it randomly choose a different string. Support of TTS output is defined when the character is compiled using the Microsoft Agent Character Editor.

If you want to use sound file output for the character, specify the location for the file in the bszURL parameter. When using the HTTP protocol to download a sound file, use the Prepare method to ensure the availability of the file before using this method. You can use the bszText parameter to specify the words that appear in the character's word balloon. If you specify a linguistically enhanced sound file (.LWV) for the bszURL parameter and do not specify text, the bszText parameter uses the text stored in the file.

The Speak method uses the last animation played to determine which speaking animation to play. For example, if you precede the Speak command with a Play "GestureRight", the server will play GestureRight and then the GestureRight speaking animation.

If you call Speak and the audio channel is busy, the character's audio output will not be heard, but the text will display in the word balloon. The word balloon's Enabled property must also be TRUE for the text to display.

See also IAgentCharacter::Play, IAgentBalloon::Enabled, IAgentCharacter::Prepare

IAgentCharacter::Stop

HRESULT Stop(
   long dwReqID  // request ID
);

Stops the specified animation (request) and removes it from the character's animation queue.

• Returns S_OK to indicate the operation was successful.

dwReqID

The ID of the request to stop.

Stop can also be used to halt any queued Prepare calls.

See also IAgentCharacter::Prepare, IAgentCharacter::StopAll

IAgentCharacter::StopAll

HRESULT StopAll();
   long lType,  // request type

Stops all animations (requests) and removes them from the character's animation queue.

lType

A bit field that indicates the types of requests to stop (and remove from the character's queue), comprised from the following:

See also IAgentCharacter::Stop

IAgentCharacter::Wait

HRESULT Wait(
   long dwReqID,    // request ID
   long * pdwReqID  // address of request ID
);

Holds the character's animation queue at the specified animation (request) until another request for another character completes.

• Returns S_OK to indicate the operation was successful.

dwReqID

The ID of the request to wait for.

pdwReqID

Address of a variable that receives the Wait request ID.

Use this method only when you support multiple (simultaneous) characters and want to sequence their interaction (as a single client). (For a single character, each animation request is played sequentially--after the previous request completes.) If you have two characters and want one character's animation request to wait until the other character's animation completes, set the Wait method to the other character's animation request ID.