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.
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.
Using Active Messaging is more efficient than using API functions for the following reasons:
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:
Dim objSession as Object or Dim objSession as MAPI.Session) and uses that object’s 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—you 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).
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.]
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
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:
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—the Messages collection object. The Messages collection is a child object of the Folder object.
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’s 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
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
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—they 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
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
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.
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 “MS Exchange Settings” as follows:
'Log on to the Session.
oSess.Logon “MS 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 = “Test Subject from Active Messaging”
oMsg.Text = “Test Text from Active Messaging”
Set oRecipTo = oMsg.Recipients.Add
oRec.Name = “x@y.com”
oRec.Type = ActMsgTo
oRec.Resolve
Set oRecipCC = oMsg.Recipients.Add
oRec.Name = “z@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—it 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.
Whatever code you write in Visual Basic will work with Microsoft Visual Basic Scripting Edition (VBScript) with some minor alterations—the main one concerning the variable declarations. There is only one variable type in VBScript—Variant. 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.
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:
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.
