IAgent

IAgent defines an interface that allows applications to load characters, receive events, and check the current state of the Microsoft Agent Server.

Methods in Vtable Order

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::GetSuspended

HRESULT GetSuspended(
   long * pbSuspended  // address of variable for suspended flag
);

Retrieves whether the Microsoft Agent server is currently suspended.

• Returns S_OK to indicate the operation was successful.

pbSuspended

Address of a variable that receives TRUE if the Microsoft Agent server is in the suspended state and FALSE if not.

Microsoft Agent loads in a suspended state when a client application attempts to start it up after the user has previously quit (by choosing the Exit command on the Microsoft Agent taskbar icon). In the suspended state Microsoft Agent handles connection requests, but returns failure on any animation methods. Therefore, a character cannot be displayed in this state. Client applications can advise users to restart the server (by choosing Restart on the taskbar pop-up menu), but cannot restart the server directly.

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:

pdwCharID

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

pdwReqID

Address of a variable that receives the Load request ID.

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

The vLoadKey parameter also enables you specify your own data provider (that would be loaded separately) that can have its own methods for loading animation data. You need to create a data provider object only if you supply character data in special formats.

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.

See also IAgent::Unregister

IAgent::UnLoad

HRESULT UnLoad(
   long * dwCharID  //character ID
);

Unloads the character data for the specified character from the Characters collection.

• Returns S_OK to indicate the operation was successful.

dwCharID

The character's ID.

Use this method when you no longer need a character, to free up memory used to store information about the character. If you access the character again, use the Load method.

See also IAgent::Load

IAgent::Unregister

HRESULT Unregister(
   long dwSinkID  //notification sink ID
);

Unloads the character data for the specified character from the Characters collection.

• Returns S_OK to indicate the operation was successful.

dwSinkID

The notification sink ID.

Use this method when you no longer need Microsoft Agent services, such as when your application shuts down.

See also IAgent::Register