没有合适的资源?快使用搜索试试~ 我知道了~
资源推荐
资源详情
资源评论
Programming the Microsoft Agent Server Interface
ActiveX® technology for interactive software agents
Microsoft Corporation
October 1998
Note: This document is provided for informational purposes only and Microsoft
makes no warranties, either expressed or implied, in this document. The entire risk
of the use or the results of this document remains with the user.
Information in this document is subject to change without notice. Companies, names,
and data used in examples herein are fictitious unless otherwise noted. No part of
this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of
Microsoft Corporation.
Microsoft may have patents or pending patent applications, trademarks, copyrights,
or other intellectual property rights covering subject matter in this document. The
furnishing of this document does not give you any license to these patents,
trademarks, copyrights, or other intellectual property rights. Microsoft, MS, MS-DOS,
Windows, Windows NT, and the Windows logo are either registered trademarks or
trademarks of Microsoft Corporation in the U.S. and/or other countries. Other
product and company names mentioned herein may be the trademarks of their
respective owners.
Contents
Introduction
Adding Microsoft Agent Functionality to Your Application
Loading Character and Animation Data
Creating a Notification Sink
Accessing Services Using Java
Accessing Speech Services
Reference
#
Introduction
Microsoft Agent provides services that enable you to program animated characters from an
application. These services are implemented as an OLE Automation server. OLE Automation
enables an application to control another application’s object programmatically. This document
assumes an understanding of the Component Object Model (COM) and OLE. For an
introduction of these services, see the Programming Interface Overview. Sample programs are
available at the Microsoft Agent Web site at http://www.microsoft.com/msagent/.
#
Adding Microsoft Agent Functionality to Your Application
#
Topic1
#
Topic2
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/sitebuilder/workshop/imedia/agent/licensing.asp).. You can
then download Agent’s self-installing cabinet 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 cabinet 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 (NT5) because that
version of the operating system already includes its own version of Agent.
To successfully install Agent on a target 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.
#
Loading Character and Animation Data
Once you have a pointer to the IAgentEx interface, you can use the Load method to load a
character and retrieve its IAgentCharacterEx interface. There are three different possibilities
for the Load path of a character. The first is compatible with Microsoft Agent 1.5 where the
specified path is the full path and filename of a character file. The second possibility is to
specify the filename only, in which case, Agent looks in its Chars directory. The last possibility
is to supply an empty Variant parameter that causes the default character to be loaded.
// Create a variant to store the filename of the character to load
const LPWSTR kpwszCharacter = L"merlin.acs";
VariantInit(&vPath);
vPath.vt = VT_BSTR;
vPath.bstrVal = SysAllocString(kpwszCharacter);
// Load the character
hRes = pAgentEx->Load(vPath, &lCharID, &lRequestID);
// Get its IAgentCharacterEx interface
hRes = pAgentEx->GetCharacterEx(lCharID, &pCharacterEx);
You can use this interface to access the character’s methods:
// Show the character. The first parameter tells Microsoft
// Agent to show the character by playing an animation.
hRes = pCharacterEx->Show(FALSE, &lRequestID);
// Make the character speak
bszSpeak = SysAllocString(L"Hello World!");
hRes = pCharacterEx->Speak(bszSpeak, NULL, &lRequestID);
SysFreeString(bszSpeak);
When you no longer need Microsoft Agent services, such as when your client application shuts
down, release its interfaces. Note that releasing the character interface does not unload the
character. Call the Unload method to do this before releasing the IAgentEx interface:
// Clean up
if (pCharacterEx) {
#
Topic3
// Release the character interface
pCharacterEx->Release();
// Unload the character. NOTE: releasing the character
// interface does NOT make the character go away. You must
// call Unload.
pAgentEx->Unload(lCharID);
}
// Release the Agent
pAgentEx->Release();
VariantClear(&vPath);
#
Creating a Notification Sink
To be notified of events by Microsoft Agent, you must implement either the IAgentNotifySink
or the IAgentNotifySinkEx interface, and create and register an object of that type following
COM conventions:
// Create a notification sink
pSinkEx = new AgentNotifySinkEx;
pSinkEx->AddRef();
// And register it with Microsoft Agent
hRes = pAgentEx->Register((IUnknown *)pSinkEx, &lNotifySinkID);
Remember to unregister your notification sink when your application shuts down and releases
Microsoft Agent’s interfaces.
#
Accessing Services Using Java
You can also access Microsoft Agent services from a Java applet. Many of the functions
accessible through the Microsoft Agent interfaces return values through parameters passed by
reference. In order to pass these parameters from Java, it is necessary to create single-
element arrays in your code and pass them as parameters to the appropriate function. If you're
using Microsoft Visual J++™ and have run the Java Type Library Wizard on the Microsoft
Agent server, refer to the summary.txt file to review which functions require array arguments.
The procedure is similar to that in C; you use the IAgentEx interface to create an instance of
the server, then load the character:
private IAgentEx m_AgentEx = null;
#
Topic4
#
Topic5
private IAgentCharacterEx m_Merlin[] = {null};
private int m_MerlinID[] = {-1};
private int m_RequestID[] = {0};
private final String m_CharacterPath = "merlin.acs";
public void start()
{
// Start the Microsoft Agent Server
m_AgentEx = (IAgentEx) new AgentServer();
try
{
Variant characterPath = new Variant();
characterPath.putString(m_CharacterPath);
// Load the character
m_AgentEx.Load(characterPath,
m_MerlinID,
m_RequestID);
}
The procedure is slightly different when loading characters from a HTTP remote location such
as a Web site. In this case the Load method is asynchronous and will raise a COM exception
of E_PENDING (0x8000000a). You will need to catch this exception and handle it correctly as
is done in the following functions:
// Constants used in asynchronous character loads
private final int E_PENDING = 0x8000000a;
private final int NOERROR = 0;
// This function loads a character from the specified path.
// It correctly handles the loading of characters from
// remote sites.
// This sample doesn't care about the request id returned
// from the Load call. Real production code might use the
// request id and the RequestComplete callback to check for
// a successful character load before proceeding.
public int LoadCharacter(Variant path, int[] id)
{
int requestid[] = {-1};
int hRes = 0;
try
{
// Load the character
m_AgentEx.Load(path, id, requestid);
}
catch(com.ms.com.ComException e)
剩余63页未读,继续阅读
资源评论
zombie_IISE
- 粉丝: 0
- 资源: 3
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功