荔园在线
荔园之美，在春之萌芽，在夏之绽放，在秋之收获，在冬之沉淀
[回到开始]
[上一篇][下一篇]
发信人: Jobs (温少), 信区: Visual
标 题: Developing Messaging Applications the ActiveX Way
发信站: BBS 荔园晨风站 (Mon Nov 29 19:20:41 1999), 站内信件
Developing Messaging Applications the ActiveX Way
Venu Yerra
MSDN Content Development Group
July 1997
Click to copy the files for the ACTMSG application for this technical article.
Note The Active Messaging 1.1 documentation, referenced throughout this
article, is a subset of the Platform Software Development Kit (SDK)
documentation, which can be found in the MSDN Library in the SDK Documentation
bin.
The Exchange team has finished work on the next version of Active Messaging,
with greatly expanded features and functionality. In fact, with the addition of
all the new features, the technology is no longer solely for messaging, so it
was renamed. Look for the Collaboration Data Objects Library (CDO) 1.2 (and
updated documentation) to replace Active Messaging soon. All Active Messaging
1.1 applications will be fully compatible with the Collaboration Data Objects
Library 1.2.
Introduction
Microsoft provides messaging, the capability to send and receive e-mail, as
part of the Windows? operating system. Prior to Active Messaging, programming
an application to provide messaging meant using the functions and structures of
the Windows Messaging API (MAPI). The programmer had the choice of using Simple
MAPI, Common Messaging Calls, or Extended MAPI, depending on the level to which
the programmer wanted to provide messaging in his or her application. The API
was good and powerful, but using it involved a lot of effort and time. Active
Messaging is a COM wrapper around MAPI that encapsulates the functions and
provides an object model for messaging development.
Why Active Messaging?
Using Active Messaging is more efficient than using API functions for the
following reasons:
Compared to the function-call interfaces of traditional API libraries, COM
objects allow for faster development and yield code that is easier to read,
debug, and maintain.
Using an API always means that you are dependent on the functions you are using
and that there is no version control. If a function changes or is no longer
included in an API, then any code that uses this function has to be modified or
replaced entirely with a new function.
Using API functions is more complex and cumbersome. With a COM object, many
coding details are encapsulated. You only have to set the attributes of the
object and call the appropriate methods.
The Active Messaging Library also takes care of many programming details for
you, such as memory management and keeping count of the number of objects in
collections.
The Active Messaging Library does not replace MAPI; it is a COM object that
interacts with underlying MAPI interfaces, as described in the following list
from the Active Messaging documentation:
Service providers implement COM interfaces梥pecifically, the MAPI interfaces梐s
described in the MAPI documentation.
The Active Messaging Library implements several objects (Session, Message, and
so on) that act as clients to these MAPI interfaces. That is, the Active
Messaging Library objects obtain pointers to the MAPI interfaces and call
methods.
The Active Messaging Library implements IDispatch and acts as an Automation
server so that it can be called by tools that can use IDispatch, such as
Microsoft? Visual Basic?. That is, it allows other programs to call its
IDispatch interface. Beginning with version 1.1, the Active Messaging Library
is self-registering as an Automation server.
The Active Messaging Library publishes a type library that contains information
about the objects that it makes available through IDispatch interface.
Your Visual Basic application acts as a client to the Active Messaging Library.
It reads the Active Messaging Library抯 type library to obtain information
about the objects, methods, and properties. When your Visual Basic application
declares a variable as an object (with code such as Dim objSession as Object or
Dim objSession as MAPI.Session) and uses that object抯 properties and methods
(with code such as MsgBox objSession.Class), Visual Basic makes calls to
IDispatch on your behalf.
For the purpose of this article, I'll assume that you have a basic knowledge of
using objects in Visual Basic and of messaging concepts such as folders,
attachments, and recipients. For an introduction to basic messaging concepts,
please see "Win32 Messaging (MAPI)" (MSDN Library, SDK Documentation, Platform
SDK).
Active Messaging is an ActiveX? library provided with an extensive set of
objects exclusively for messaging. You are not required to use the user
interface provided with the library梱ou can provide your own interface. As the
Active Messaging documentation states, "This library lets you add to your
application the ability to send and receive mail messages with or without
attachments and to interact with folders and address books. You can create
programmable messaging objects, then use their properties and methods to meet
the needs of your application."
Being a COM object, Active Messaging can be used with any development tool or
technology that supports Automation, such as any Microsoft Visual Studio?
development system component or Active Server Pages (ASP).
Installation
The following installation instructions are from the Active Messaging
documentation:
The Active Messaging Library version 1.1 is installed with the MAPI component
of the Platform Software Development Kit (SDK) and with the Microsoft Exchange
Client. The setup programs register the Active Messaging Library for subsequent
use by Automation controllers, that is, applications that support Automation
like Visual Basic.
Note No separate setup program is provided or needed for the Active Messaging
Library.
When you use the Active Messaging Library with an Automation controller, verify
that the tool has referenced the Active Messaging Library. For example, when
you are using Microsoft Visual Basic version 4.0, choose the References command
from the Tools menu, and select the check box for Microsoft Active Messaging
1.1 Object Library. [Editor's note: In Visual Basic 5.0, the References command
can be found on the Project menu.]
Active Messaging Object Model
A wide discussion of the Active Messaging object model is beyond the scope of
this article. For more details about Active Messaging, please see the Active
Messaging documentation (MSDN Library, SDK Documentation, Platform SDK).
But, what follows is an introduction to the Active Messaging object model.
Figure 1 represents the top of the hierarchy.
Figure 1. The top of the Active Messaging Library hierarchy
View full object model.
As you can see in the figure, the library has only one top-level object, called
Session. Creating a Session object is necessary in order to use any other
objects in Active Messaging. Once the Session object is created and logged on
to, all the other objects become available. As illustrated, the Session object
has only three child objects:
The AddressLists collection
The Infostores collection
The Folder (Inbox/ Outbox) object
Inbox and Outbox, the top folder objects, are available in the library by
default. This means that they need not be added to the Folders collection
(which appears further down the hierarchy). All subsequent folders that get
created are subfolders.
Apart from these three child objects, I will highlight one of the most
important objects in Active Messaging梩he Messages collection object. The
Messages collection is a child object of the Folder object.
AddressLists Collection
The AddressLists collection, illustrated in Figure 2, is described in the
Active Messaging documentation as follows:
The AddressLists collection provides access to the root of the MAPI address
book hierarchy for the current session. You can obtain the collection through
the parent Session object抯 AddressLists property. Each AddressList object
represents one MAPI address book container. The AddressLists collection
contains only those AddressList objects that contain recipients, and not those
containing only subcontainers.
This object is used either to get information about an address book and its
recipients or to add, modify, or delete recipients.
Figure 2. The AddressLists collection hierarchy
View full object model.
Infostores Collection
The Infostores collection, illustrated in Figure 3, is described in the Active
Messaging documentation as follows:
An InfoStores collection provides access to all InfoStore objects available to
this session. Each InfoStore object in turn offers access to the folder
hierarchy of that message store. This is used primarily to obtain access to
public and private folders. The Active Messaging Library does not support
methods to add or remove InfoStore objects from the collection.
This object can be used to iterate through different folders for information
regarding messages inside the folders and to add, modify, or delete messages,
folders, and so on.
Figure 3. The InfoStores collection hierarchy
View full object model.
Folder (Inbox/Outbox)
As we have discussed earlier, the objects in the library are available once the
Session object is created and the Logon method is successful. At this point,
the Session object also allows you to interact with the default objects. Two of
these are the top folder objects, Inbox and Outbox.
You need not create these two folders梩hey are already available in the
library. The Inbox/Outbox object model is illustrated in Figure 4. As you can
see, the Folders collection object is a child of the top folder objects. The
Inbox object receives all incoming messages and the Outbox stores all outgoing
messages.
Figure 4. The Folder object hierarchy
View full object model.
Messages Collection
This object is one of the most important objects in the Active Messaging
Library because the Message object is a child object of this collection. The
Message object is the object on which most of the actual actions are done, such
as sending a message, reading a received message, and so on. Although the
Messages collection is a child object of the Folder object, I have illustrated
its object model separately in Figure 5.
Figure 5. The Messages collection hierarchy
View full object model.
As you may have noticed, the smallest available object in Active Messaging is
called a Field object. A Field object represents a Messaging property of an
Active Messaging Library object.
Visual Basic Sample Code
The ACTMSG sample associated with this article sends a simple mail message
using an interface provided in the Visual Basic form, message.frm. Before you
run the sample you need to set the references in Visual Basic to the Active
Messaging Library.
Most of the code for this sample is in actmsg.vbp. There is also the
message.frm form, which has one textbox each for To Recipients, CC Recipients,
Message Subject, and Message Text and one command button that contains the code
for sending the message.
Let's step through the basics of creating and sending a message.
Declare the objects that are to be used. The Session object, once created and
logged on to, provides a way to use other objects, such as Messages, Recipients,
and Folders, which actually perform the actions of sending and receiving
e-mail. Because this sample code illustrates a simple way of sending mail, I am
creating only the objects that I require: Session, Message, and Recipient.
Dim oSess As Mapi.Session
Dim oMsg As Mapi.Message
Dim oRecipTo As Mapi.Recipient
Dim oRecipCC As Mapi.Recipient
The above declaration, oSess as Mapi.Session, is possible only through early
binding. Without early binding, you would need to use the following:
Dim oSess as Object
'Create an object of Session.
Set oSess = CreateObject("Mapi.Session")
After the session object is successfully created, use the Logon method on the
session object with either a default profile or a specific profile. If you are
already using Microsoft Exchange or Outlook? then you can use the default
profile 揗S Exchange Settings? as follows:
'Log on to the Session.
oSess.Logon 揗S Exchange Settings?
Create a Message object in the Messages collection of the Outbox. Set the
different attributes of the Message object as shown below.
The Message object needs a Recipients collection. So for every recipient,
create a Recipient object and add it to the Recipients collection of the
Message object. The RecipientType attribute differentiates a RecipientTo from a
RecipientCC. Also, call the Resolve method on all the Recipient objects.
'Create a message and fill in its properties.
Set oMsg = oSess.Outbox.Messages.Add
oMsg.Subject = 揟est Subject from Active Messaging?
oMsg.Text = 揟est Text from Active Messaging?
Set oRecipTo = oMsg.Recipients.Add
oRec.Name = 搙@y.com?
oRec.Type = ActMsgTo
oRec.Resolve
Set oRecipCC = oMsg.Recipients.Add
oRec.Name = 搝@y.com?
oRec.Type = ActMsgCC
oRec.Resolve
After all the attributes are set, call the Update method of the Message. This
saves the message in the MAPI system. The message is actually sent when the
Send method is called. The Update method is not required if the makePermanent
parameter is set to True when the Send method is called. When set to True, the
makePermanent parameter does the same thing as calling the Update method梚t
saves the message in the MAPI system.
' Send the message.
oMsg.Update
oMsg.Send
Log off from Session so that all the resources being used by the Session are
freed. This is required when you finish using the Active Messaging system.
'Log off the session.
oSess.Logoff
'Clear all the objects before exiting the procedure.
Set oRecipTo = Nothing
Set oRecipCC = Nothing
Set oMsg = Nothing
Set oSess = Nothing
This is just a small part of the sample that shows how to send a message. But
there are other things you can do as well: open the AddressLists collection and
browse the AddressList; open AddressEntry and view the attributes of a
particular address; open a specific folder and parse through all the messages
in the folder or try to locate a specific message; and read mail that was
received. You can also send attachments with mail.
An exhaustive list of the objects available in the Active Messaging Library,
along with their attributes and methods, is available in the Active Messaging
SDK documentation (MSDN Library, SDK Documentation, Platform SDK). I recommend
that you read through the documentation for help with designing your
application efficiently. With the amount of flexibility provided in this
library, you can build an extremely powerful messaging application.
Visual Basic Scripting Edition Sample
Whatever code you write in Visual Basic will work with Microsoft Visual Basic
Scripting Edition (VBScript) with some minor alterations梩he main one
concerning the variable declarations. There is only one variable type in
VBScript梀ariant. All the variables that were declared in Visual Basic should
be stripped of their data type.
For example:
Dim iTemp As Integer
In VBScript would become:
Dim iTemp
The VBScript code has been provided as a text file named actmsg.txt. Also,
there is an HTML file, actmsg.htm, included with the ACTMSG sample that can be
used for sending mail from a browser.
Using Active Messaging with Visual C++
Because the Active Messaging Library is an ActiveX/COM library, it is available
as a set of COM interfaces that can be used from Microsoft Visual C++?. For
more information on how to use the Active Messaging Library in Visual C++, see
the following:
"MAPI Interfaces" (MSDN Library, SDK Documentation, Platform SDK)
"The Active Messaging Library and MAPI" (MSDN Library, SDK Documentation,
Platform SDK)
Conclusion
This article has explained the basic concepts of the Active Messaging system.
Active Messaging is robust, easy to use, and object-based. It conforms to COM
specifications, so all the features of COM are applicable to Active Messaging,
such as application customization, distributed computing, language independence,
and so forth. If you need to add messaging capability to an existing
application, or if you are developing a complete messaging application, Active
Messaging is the way to go.
The Full Active Messaging Object Model
? 1999 Microsoft Corporation. All rights reserved. Terms of use.
--
☆ 来源:．BBS 荔园晨风站 bbs.szu.edu.cn．[FROM: bbs@192.168.11.111]
[回到开始]
[上一篇][下一篇]
荔园在线首页 友情链接：深圳大学 深大招生 荔园晨风BBS S-Term软件 网络书店