Microsoft Agent的COM接口编程


Microsoft Agent具有相当广泛的用途，我们既可以把它加入到普通应用程序中供本地系统使用，也可以把它嵌入到HTML文档中供Internet/Intranet使用。Microsoft Agent支持C/C＋＋、Visual Basic、Java、JScript和VBScript等多种编程语言，并为程序员提供了OLE自动化服务器和ActiveX控件两种编程方法，从本质上讲，这两种编程方法都属于OLE技术的范畴，都建立在COM (Component Object Model，组件对象模型)的基础之上。利用VC＋＋的MFC类库或VB等支持ActiveX的编程工具可以很容易地调用ActiveX控件，但是ActiveX控件把许多OLE技术的细节都隐藏起来了，如果我们想加深对一个COM对象的了解的话，则应直接使用它的COM接口来编程，从这一点出发，本文将介绍Microsoft Agent的COM接口的基本编程方法，希望能够起到抛砖引玉的作用。

    OLE编程的基础知识

　早期的OLE(现称为OLE 1)首次出现在Windows 3.1中，其主要用途是生成复合型文档，使得一个应用程序的文档可以通过链连或嵌入的方式包含其它应用程序的数据(对象)。随着软件组件技术变得日益重要起来，Microsoft在OLE 1的基础上设计了OLE 2，利用它可以实现二进制级上可重用的软件组件，并且控制这些组件的版本和扩充其功能变得相当容易。由于OLE 2的体系结构被设计成为开放式的、可扩充的，所以以后不会再出现OLE 3或4。经过多年的发展，如今的OLE已经包括了OLE自动化、COM、COM＋、DCOM和ActiveX等多项技术，它们是ActiveDirectory(将用于NT 5.0的一项关键技术)、OLE Messaging、DirectX 、Active Controls、ActiveX Scripting和Task Scheduler等等多种新技术的基础，OLE已不再是Object Linking and Embedding的缩写，它变成了一个独立的单词，专门用来表示Microsoft的软件组件集成技术。

　　COM是OLE技术的基础，它规定了对象之间如何相互通讯，符合COM规范的对象也叫做COM对象。按照COM的规定，对象内部可以使用任何语言来编写，它们通过接口(Inte易做图ce)来与外界通信。所谓接口是指对象提供的一组特定的功能调用(方法)，每个对象可以有多个接口，不同的对象可以实现同一种接口，客户程序通过对象的接口指针来调用对象的功能。由于OLE规定了组件在二进制级上可重用，客户程序不能够直接访问对象内部的数据，读取或设置对象的属性也都要通过接口来进行。每一种接口都是从一个叫IUnknown接口继承而来，都必须重新实现IUnknown的三个方法：QueryInte易做图ce、AddRef和Release，客户程序调用QueryInte易做图ce可以获得对象的其它接口指针，AddRef和Release分别将对象的引用计数加一和减一，当引用计数为零时，对象就会被释放。客户程序调用COM对象的一般步骤是首先创建一个对象，然后获取需要的接口指针，调用相应的功能，最后释放接口指针和对象。

　　 C＋＋程序调用Microsoft Agent的基本方法

　　根据前面介绍的基础知识，下面我们来看看C＋＋程序中如何调用Microsoft Agent。

　　1.设置与选项

　　本文使用的编程工具为Visual C＋＋ 5.0，程序为一般的Win32应用程序，为了使程序能够正确地编译连接和运行，您首先需要拥有AgtSvr.h和AgtSvr—i.c两个定义Microsoft Agent的COM接口的文件，它们可以在Microsoft的MS Agent站点(http://www.microsoft.com/workshop/
prog/agent/)上找到，或者请下载Microsoft最新的Internet Client SDK或Platform SDK，其次，请在Project/Settings/Link菜单中加入以下的库：ole32.lib、oleaut32.lib、uuid.lib、odbc32.lib odbccp32.lib，最后要确保系统中安装有Microsoft Agent及动画人物数据。

　　 2.创建Microsoft Agent对象

　　创建OLE对象之前需要初始化OLE，这由OleInitialize()函数来完成，如果OLE初始化不成功，那么就无法继续执行后面的代码，创建对象由CoCreateInstance()函数来完成：

　　if (FAILED(OleInitialize(NULL))) return －1;//初始化OLE
　　hRes = CoCreateInstance(CLSID—AgentServer,NULL,CLSCTX—SERVER,IID—IAgent,(LPVOID ＊)＆pAgent);//创建Microsoft Agent Server的实例
　　if (FAILED(hRes)) return －1;

　　CoCreateInstance()的第一个参数是对象的CLSID(类代码)，Microsoft Agent Server的CLSID为定义在AgtSvr—i.c文件中的CLSID—AgentServer，这个128位的编码唯一地标识了Agent服务器，服务器所在路径和运行参数等信息都放在系统注册表中；第二个参数一般情况下设为NULL；第三个参数用来指明对象的运行环境，如远程或本地，此处设为CLSCTX—SERVER；第四个参数指明用来与对象通信的接口的ID，这也是一个128位的编码，Agent的接口ID为IID—IAgent；第五个参数是用来接收IAgent的接口指针。

　　如果Microsoft Agent Server还没有在内存中运行，那么CoCreateInstance()会启动它并创建一个Agent对象，如果服务器已经运行了，则CoCreateInstance()会与之连接并创建一个Agent对象。当所有的Agent对象都被释放了后，服务器自动退出。

　　 3．装入动画人物数据

　　下面的代码调用IAgent::Load()方法来装入一个动画人物的数据，由于Agent服务器在自己的内存空间中运行，所以传送的字符串变量需要用SysAllocString()来分配内存：

　　VariantInit(＆vPath); //初始化OLE变量
　　vPath.vt = VT—BSTR; //指明变量类型为Unicode的字符串
　　vPath.bstrVal=SysAllocString(kpwszCharacter);
        //kpwszCharacter为动画人物数据的存放路径
　　hRes = pAgent－>Load(vPath,＆lCharID,＆lRequestID);
        //装入数据，人物ID在lCharID中返回
　　hRes = pAgent－>GetCharacter(lCharID,＆pdCharacter);
        //获取lCharID的IDispatch接口指针调用IDispatch::QueryInte易做图ce()方法可以得到                //IAgentCharacter的接口指针：
　　hRes = pdCharacter－>QueryInte易做图ce(IID—IAgentCharacter, (LPVOID ＊)＆pCharacter);
　　pdCharacter－>Release(); //释放IDispath

　　通过IAgentCharacter接口就可以调用动画人物支持的各种方法了：

　　hRes = pCharacter－>Show(FALSE, ＆lRequestID);//显示动画人物
　　hRes = pCharacter－>MoveTo(320,240,100,＆lRequestID); //移动动画人物到屏幕中央
　　bszSpeak = SysAllocString(L"Hello World!"); //分配字符串
　　hRes = pCharacter－>Speak(bszSpeak, NULL, ＆lRequestID); //让动画人物说话
　　SysFreeString(bszSpeak); //释放字符串所占内存

　　 4．释放对象

　　程序在退出之前需要把创建的Agent对象释放：

　　if (pCharacter) {
　　pCharacter－>Release(); //释放IAgentCharacter接口
　　pAgent－>Unload(lCharID); //卸载动画人物数据
　　}
　　pAgent－>Release(); //释放Agent对象
　　VariantClear(＆vPath); //清除OLE变量

　　 进一步的编程要点

　　前面介绍的是调用Microsoft Agent服务器最基本的一些步骤，为了完成比较实际的任务，客户程序还应根据自己的情况考虑下面的一些编程要点。

　　 1．检查Agent Server的版本

　　OLE要求组件或对象具有向后兼容性，高版本对象支持低版本对象的所有接口和属性，这样可以很方便地进行组件升级。客户程序通常应检查对象的版本，只有系统中安装的对象的版本号高于或等于所期望的版本号时才能调用对象。下面的IsValidAgentVersion()函数检查Microsoft Agent的版本号，并将它与定义在AgtSvr.h文件中的版本号相比较：

　　BOOL IsValidAgentVersion(IAgent ＊pAgent) {
　　IDispatch ＊pdAgent = NULL;
　　ITypeInfo ＊pTypeInfo = NULL;
　　ITypeLib ＊pTypeLib = NULL;
　　TLIBATTR ＊pTypeLibAttr = NULL;
　　BOOL bValid = FALSE;
　　UINT uiIndex;
　　pAgent－>QueryInte易做图ce(IID—IDispatch, (LPVOID ＊)＆pdAgent);
　　pdAgent－>GetTypeInfo(0, 0, ＆pTypeInfo)； //取得类型信息
　　pTypeInfo－>GetContainingTypeLib(＆pTypeLib, ＆uiIndex);//取得类型库
　　pTypeLib－>GetLibAttr(＆pTypeLibAttr); //取得类型库中的属性
　　if ((pTypeLibAttr－>wMajorVerNum > AGENT—VERSION—MAJOR) ||((pTypeLibAttr－>wMajorVerNum == AGENT—VERSION—MAJOR) ＆＆(pTypeLibAttr－>wMinorVerNum >= AGENT—VERSION—MINOR)))
　　bValid = TRUE; //期望的版本号定义在AgtSvr.h文件中
　　if (pTypeLib) {
　　if (pTypeLibAttr) pTypeLib－>ReleaseTLibAttr(pTypeLibAttr);
　　pTypeLib－>Release(); }
　　if (pTypeInfo) pTypeInfo－>Release();
　　if (pdAgent) pdAgent－>Release();
　　return bValid;}

　　 2．实现IAgentNotifySink接口

　　为了能够处理用户的输入，了解Agent对象的状态，客户程序应实现IAgentNotifySink接口来接收Agent对象的事件。IAgentNotifySink的声明和缺省实现可以在Platform SDK或Internet Clinet SDK中的Notify.h和Notify.cpp中找到，客户程序应根据需要修改某些事件的处理函数
。下面的代码向Agent对象注册IAgentNotifySink接口，其中AgentNotifySink是从IAgentNotifySink继承而来：

　　pSink = new AgentNotifySink;
　　pSink－>AddRef(); //增加引用计数
　　hRes = pAgent－>Register((IUnknown ＊)pSink, ＆lNotifySinkID);//进行注册
　　...
　　if (pSink) {
　　p

补充：软件开发 , C语言 ,