IAgentCharacter::Prepare

[Microsoft Agent is deprecated as of Windows 7, and may be unavailable in subsequent versions of Windows.]

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:

Value	Description
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.

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:

	Description
"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.

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.

If you load a character using the HTTP protocol (an .ACF file), you must use the Prepare method to retrieve animation data before you can play the animation. You cannot use this method if you loaded the character using the UNC protocol (an .ACS file). You also cannot retrieve HTTP data for a character using Prepare if you loaded that character using the UNC protocol (.ACS character file).

Animation or sound data retrieved with the Prepare method is stored in the browser's cache. Subsequent calls will check the cache, and if the animation data is already there, the control loads the data directly from the cache. Once loaded, the animation or sound data can be played with the Play or Speak methods.

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