Microsoft Agent's COM Interface Programming
Microsoft Agent (For details on this technology, please refer to "China Computer News" 1997
"Microsoft Agent" "One article" in the 46th issue of "One article) has a wide range of purposes, we can
Add it to a normal application for local systems, or embed it into the HTML document
Internet / Intranet is used. Microsoft Agent supports C / C , Visual Basic,
Java, JScript and VBScript and other programming languages, and provide programmers with OLE automation services
The two programming methods of the ActiveX control, from essentially, these two programming methods belong to OLE technology
The category is based on the COM (Component Object Model, component object model).
Using VC MFC class or VB and other programming tools to support ActiveX can be easily called
ActiveX control, but ActiveX controls hide the details of many OLE technology, if we
If you want to deepen an understanding of a COM object, you should use its COM interface directly to program, from this
Start, this article will introduce the basic programming method of the COM interface of Microsoft Agent, I hope to be able to start
The role of the throwing jade.
OLE Programming Basic Knowledge
Early OLE (now OLE 1) first appeared in Windows 3.1, the main purpose is to generate
The combination document allows the document of an application to include other applications by chain or embedded.
Program data (object). With the increasing software component technology, Microsoft is OLE 1
OLE 2 is designed on the basis, using it to realize software components that can be reused in binary grade, and control
The version of these components and the expansion of its function becomes quite easy. Since the architecture of OLE 2 is designed
For open, OLE 3 or 4 will not appear again in the future. After years of development, such as
Today's OLE has included OLE automation, COM, COM , DCOM, and ActiveX, etc.
Is ActiveDirectory (a key technology that will be used for NT 5.0), OLE MESSAGING, DIRECTX
Active Controls, ActiveX Scripting and Task Scheduler, etc.
Basic, OLE is no longer an abbreviation for Object Linking and Embedding, it has become an independent
The word is specifically used to represent the software component integration technology of Microsoft.
COM is the foundation of OLE technology, which specifies how objects are communicating with each other, complying with COM specification
I am also called COM objects. According to COM, you can use any language inside to write, they
Communicate with external interfaces through the interface. The so-called interface refers to a set of specific functions provided by the object.
Call (Method), each object can have multiple interfaces, different objects can realize the same interface, guest
The user program calls the function of the object through the object's interface pointer. Since the OLE specifies the component in binary level
The function of the object can be retrieved. Since the OLE specifies that the components can be reused on the binary stage, the client is not
It is also possible to pass the data within the object inside the object, read or set the properties of the object.
Each interface must be re-implemented from iUnknown from a part of an IUNKNOWN interface.
Three methods: queryinterface, addref, and release, customer program call
QueryInterface can get other interface pointers of the object, addRef and release, respectively
The reference count adds one and minus one. When the reference count is zero, the object will be released. The general step of customer program call COM object is to first create an object, then get the required interface pointer, call the corresponding work.
Energy, finally release the interface pointer and object.
Basic approach to c program calls Microsoft Agent
Based on the basics described above, let's take a look at how to call Microsoft in the C program.
Agent.
Setting and option
The programming tools used herein are Visual C 5.0, and the program is a general Win32 application.
In order to make the program correctly compile and run, you first need to have Agtsvr.h and AgtsVR-I.
c
Two files that define the COM interface of Microsoft Agent, they can be in Microsoft MS
Agent site (http://www.microsoft.com/workshop/prog/agent/) found, or please
Download Microsoft's latest Internet Client SDK or Platform SDK, follow, please
The following libraries are added to the Project / Settings / Link menu: ole32.lib, oleaut32.lib,
UUID.LIB, ODBC32.LIB ODBCCP32.LIB, finally make sure uuid.lib, odbc32.lib
Odbccp32.lib, and finally make sure that Microsoft Agent and animated people data are installed in the system.
2. Create a Microsoft Agent object
Before creating an OLE object, you need to initialize OLes, which is done by the oleinitialize () function, if
Ole
Initialization is unsuccessful, then you can't continue to perform the following code, create an object
CoCreateInstance ()
Function to complete:
IF (Failed (Oleinitialize)) Return -1; //
Initialization OLE
HRES = CocreateInstance (CLSID-Agent Server, Null, ClsctX-Server,
IID-IAGENT, (LPVOID *) & Pagent); // Create an instance of Microsoft Agent Server
IF (Failed (HRES) RETURN -1;
The first parameter of COCREATEINSTANCE () is the CLSID of the object (class code), Microsoft
The CLSID of Agent Server is the CLSID-AgentServer defined in the AgtsVR-I.c file.
This 128-bit encoding uniquely identifies the Agent server, the path and running parameters of the server, etc.
The information is placed in the system registry; the second parameter is in general to null; the third parameter is used
Indicates the operating environment of the object, such as remote or local, set to CLSCTX-Server; fourth parameters
Indicates the ID used to communicate with the object, this is also a 128-bit encoding, the Agent interface ID is
IID-IAGENT; the fifth parameter is used to receive the interface pointer of the IAgent.
If Microsoft Agent Server has not yet run in memory, then
CoCreateInstance () will start it and create an agent object if the server has already runned,
The cocreateInstance () will be connected to it and create an Agent object. When all Agent objects
After being released, the server automatically exits.
3. Mount animation
The following code calls the iAgent :: load () method to load the data of an animated person, because the Agent server runs in its own memory space, so the transmitted string variable needs to be used.
SysallocString () to allocate memory:
Variantinit (& VPATH); / / Initializing the OLE variable
vpath.vt = vt-bstr; / / indicates a string of the variable type Unicode
vpath.bstrval = sysallocstring (kpwszcharacter); // kpwszcharacter
Storage path for animated character data
HRES = PAGENT-> LOAD (vPath, & lcharid, & lrequestid); // Load data,
Character ID Returns in LCharid
HRES = Pagent-> getCharacter (Lcharid, & pdcharacter); // Get
LCharid IDSPATCH interface pointer
Call the idispatch :: queryinterface () method You can get the pickup of IAGENTCHARACTER
Inlet pointer:
HRES = PDCharacter-> queryinterface (IID-IAGENTCHARACTER,
(Lpvoid *) & pcharacter;
PDCharacter-> release (); // Release iDispath through IAGENTCHARACTER
The mouth can call the various methods supported by animation:
HRES = PCharacter-> show (false, & lrequestid); // Show animation characters
HRES = PCharacter-> MoveTo (320, 240, 100, & lrequestid); // Mobile
Draw people to the center of the screen
Bszspeak = sysallocstring (l "Hello World!"); // Assign strings
HRES = PCharacter-> Speak (bszspeak, null, & lrequestid); //
Painted people talk
Sysfreestring (BSZSpeak); // Release the string of memory
4. Release object
The program needs to release the created Agent object before exiting:
IF (pCharacter) {
PCharacter-> release (); // Release the IAGENTCHARACTER interface
Pagent-> unload (lcharid); // Uninstall the animated character data
}
Pagent-> Release (); // Release the Agent object
VariantClear (& vpath); / / Clear the OLE variable
VariantClear (& vpath); / / Clear the OLE variable
Further programming points
The previous introduction is to call the most basic steps of the Microsoft Agent server, in order to finish
Come into a relatively actual task, the customer program should also consider some of the programming points below according to their own situation.
1. Check the version of Agent Server
OLE requires that components or objects have backward compatibility, high versions of the object support low version objects
There are interfaces and properties that can be easily upgraded. Customer program usually checks objects
The version, only the version number of the object installed in the system is above or equal to the desired version number
Call the object. The following isvalidagentVersion () function checks the version of Microsoft Agent
No., and compare it with the version of the version defined in the Agtsvr.h file: BOOL IsValidagentVersion (iAgent * Pagent) {
Idispatch * pdagent = null;
ITYPEINFO * ptypeinfo = null;
ITypelib * ptypelib = null;
TLIBATTR * ptypelibattr = null;
Bool bvalid = false;
Uint uiindex;
Pagent-> queryinterface (iid-idispatch, (lpvoid *) & pdagent);
PDAGENT-> GetTypeInfo (0, 0, & ptypeinfo); // acquire type information
PtypeInfo-> getContainingTypelib (& Ptypelib, & UiIndex); // Get Type Library
ptypelib-> getlibattr (& ptypelibattr); // Get the properties in the type library
IF ((ptypelibattr-> wmajorvernum> agent-version-major) ||
((ptypelibattr-> wmajorvernum == agent-version-major) &&
(ptypelibattr-> wminorvernum> = agent-version-minor))))))))
BVALID = true; // The expected version number is defined in the Agtsvr.h file
IF (ptypelib) {
IF (ptypelibattr) ptypelib-> releaselibattr (ptypelibattr);
Ptypelib-> Release ();
IF (ptypeinfo) ptypeinfo-> release ();
IF (pdagent) pDagent-> release ();
Return bvalid;}
2. Implement the IAGENTNOTIFYSINK interface
In order to process the user's input, understand the status of the Agent object, the client should be implemented
The IAGENTNOTIFYSINK interface to receive an event of an Agent object. IAGENTNOTIFYSINK
And default implementation can be in Platfo events. IAGENTNOTIFYSINK declaration and default implementation
Notify.h and notify.cp in Platform SDK or Internet Clinet SDK
Find in P, the client program should modify the processing function of certain events as needed. The following code
Agent object registrations the IAGENTNOTIFYSINK interface, where AgentNotifyInsink is from
IAGENTNOTIFYSINK inherits:
Psink = new agentNotifysink;
psink-> addref (); // increase the reference count
HRES = Pagent-> Register ((iUnknown *) psink, & lnotifysinkid;
// Register
...
IF (psink) {
Pagent-> unregister (lnotifysinkid); // Logout IAGENTNOTIFYSINK interface
Psink-> Release ();} The two events most interested in the client are RequestComplete and Command. Agent
The server uses asynchronous way to handle various requests for the client, so that the client program can be requested.
The service is carried out while making your own work, and when the server completes a request, it will be stimulated.
Requestcomplete event, the client can judge which request is over, and
The processing should be treated. The Command event is when the user uses a mouse or microphone to issue an order to the animation.
Excited, the client can understand the specific information of the command through the IAGENTUSERINPUT interface.
3. Custom command event.
IAGENTNOTIFYSINK declaration and default implementation can be on Platform SDK or Internet
CLINET SDK is found in Notify.h and Notify.cpp, the client should modify as needed.
Handling function of certain events. The following code registers the iAgentNotifySink interface to the Agent object
Among them, AgentNotifySink is inherited from IAGENTNOTIFYSINK:
Psink = new agentNotifysink;
psink-> addref (); // increase the reference count
HRES = Pagent-> Register ((iUnknown *) psink, & lnotifysinkid;
// Register
...
IF (psink) {
Pagent-> unregister (lnotifysinkid); // Logout IA
Gentnotifysink interface
Psink-> release ();
The two events most interested in the client are RequestComplete and Command. Agent
The server uses asynchronous way to handle various requests for the client, so that the customer program can
Request the service while making your own work, will stimulate when the server completes a request
RequestComplete event, the client can judge which request is over, and
Corresponding processing. The Command event is to send the animation character when the user uses a mouse or microphone.
The order is excited, the client program can understand the specific command through the IAGENTUSERINPUT interface.
information.
3. Custom command
The Agent server provides some default commands for each animated person, which appears
In the Association menu or command window, the client can add a self-definition through the IAGENTCOMMANDS interface.
Yi command.
In order to get the interface pointer of the IAGENTCOMMANDS, the parameter IID-IAGENTCOMMANDS should be used.
To call iAgentCharacter :: queryinterface (), iAgentCommands add () or
INSERT () method can join custom commands while setting CAPTION, Visible, and Voice properties,
Indicates if the command is displayed, and is displayed in the associated menu or in the command window.
The Agent server gives each command to a ID value, the client can use this ID value to call
IAGENTCOMMANDS :: getcommand () method, get the IAGENTCOMMAND interface of each command
The needle is adjusted for various properties of a single command.
4. WAV file instead of voice synthesis
Microsoft Agent currently only supports English speech-integrated functions, and only use Chinese.
The WAV file is replaced. If you send a second parameter for the iAgentCharacter :: Speak () method
The path of a WAV file, then the Agent server automatically plays this WAV file and in the text balloon
The text included in the first parameter is displayed. If the path to the second parameter passes a path to the lwv file of the audio information, you do not need to provide text in the first parameter because the LWV file contains text.
Word information. When using the LWV file, the nozzle action of the animated character can be consistent with the voice of the output.
When the WV file, the motion of the cartoons can be consistent with the voice of the output, so it is possible
Try to use the LWV file as much as possible, this format file can use Microsoft Agent Linguistic
Information Sound Editing Tool Edit WAV files to generate.
5. Other COM interfaces
In addition to the previously mentioned interfaces, Agent servers have other COM interfaces.
IAGENTCOMMANDWINDOW allows client programs to access or set up the properties of the command window, including location,
Size and whether it is visible. IAGENTSPEECHINPUTPROPERTIES allows client programs to access voice input
The properties of the function, most of which are read-only. IAGENTAUDIOOOUTPROPERTIES
A client program reads some properties of the speech output function. IAGENTPROPERTYSHEET allows clients
Order access or set the properties of the Agent server. IAGENTBALLOON allows client programs to access text
The properties of the balloon can set a few properties, such as whether it is visible and the font name. About these interfaces
Body definition and use Please refer to the help documentation of Microsoft Agent.
to sum up
Microsoft Agent is a newer technology that belongs to the category of OLE, involving deeper programming
Theory, this article is only the most basic method of use, feeling from the perspective of the OLE automation service.
Interesting readers can refer to the "Inside Ole" book published by Microsoft Press (Second Edition)
One step to understand the knowledge of OLE programming, and participate in Microsoft's Agent News Discussion Group (News Server is
Msnews.Microsoft.com, discussion group
IP 0 IP # Internet Protocol
ICMP 1 ICMP # Internet Control Message Protocol
GGP 3 GGP # Gateway-Gateway Protocol
TCP 6 TCP # Transmission Control Protocol
EGP 8 EGP # EXTERG GATEWAY Protocol
PUP 12 Pup # Parc Universal Packet Protocol
UDP 17 UDP # User DataGram Protocol
HMP 20 HMP # Host Monitoring Protocol
XNS-IdP 22 XNS-IDP # Xerox NS IDP
RDP 27 RDP # "Reliable DataGram" Protocol
RVD 66 RVD # mit Remote Virtual Disk
