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, (http://www.microsoft.com/msagent/licensing.htm). You can then download Agent's self-installing executable file from the Web site (using the Save rather than 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 executable 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 and later operating systems because these versions of the operating system already include their own version of Agent.

To successfully install Agent on a target system with a prior Microsoft Win32® operating 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 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.