Chapter 4

MAPI Architecture


CONTENTS


In Chapter 3, "What Is MAPI?," you learned the general outline of the messaging API and how MAPI fits into Microsoft's Windows Open Systems Architecture (WOSA) scheme. You also learned about the three most common types of MAPI messages (ASCII text, formatted documents or binary files, and control messages). Lastly, Chapter 3 described the three major categories of MAPI applications (e-mail, message-aware, and message-enabled).

In this chapter, you'll learn about the basic conceptual components of MAPI-the MAPI
Client and the MAPI Server. These two components work together to create, transport, and store messages within the MAPI system.

MAPI clients deal with three main objects:

Each of these objects is represented slightly differently in the various versions of MAPI implementations you'll learn about in this book. For example, the MAPI OCX tools that ship with Visual Basic allow only limited access to folders and address information. The Messaging OLE layer (provided through the MAPI 1.0 SDK) provides increased access to folders and addresses, but only the full MAPI 1.0 functions allow programmers to add, edit, and delete folders and addresses at the client level. This chapter will cover all three objects in a general sense. Later chapters will provide detailed programming examples.

MAPI servers also deal with three main objects:

As you can see, the server side of MAPI is quite similar to the client side (see Figure 4.1).

Figure 4.1 : Client and server aspects of the MAPI system.

Where the client is concerned with creating and manipulating messages, the server component is concerned with the transporting of those same messages. Where the client side is accessing storage folders, the server side is dealing with message storage, and both client and server must deal with message addresses. However, the MAPI server has the responsibility of managing the transport, storage, and addressing of messages from any number of client applications.

In addition to maintaining the message base for all local clients, MAPI servers also have the task of moving messages to and from remote servers and clients. The final section of this chapter talks briefly about a special MAPI component that handles this task-the MAPI Spooler.

When you complete this chapter, you'll understand the fundamental tasks that must be performed by all MAPI clients and MAPI servers and the basic objects maintained and manipulated by both client and server applications. Once you have a grasp of the general operations of a MAPI system, you'll be ready to explore MAPI functions from a Windows programming perspective in the coming chapters.

The MAPI Client

The MAPI Client is the application that runs on the user's workstation. This is the application that requests services from the MAPI Server. As mentioned in the preceding chapter, client applications can be generic e-mail tools such as Microsoft's Microsoft Mail or Exchange Mail Client for Windows 95. Client applications can also be message-aware applications like the Microsoft Office Suite of applications. Each of these applications provides access to the message server via a send menu option or command button. Lastly, message-enabled applications, ones that use MAPI services as a primary part of their functionality, can be built to meet a specific need. These programs usually hide the MAPI services behind data entry screens that request message-related information and then format and send messages using the available message server.

All MAPI clients must, at some level, deal with three basic objects:

Depending on the type of client application, one or more of these MAPI objects may be hidden from the client interface. However, even though they may not be visible to the application user, all three objects are present as part of the MAPI architecture. The next three sections describe each of the MAPI client objects and their functions in the MAPI model.

Messages and Attachments

The MAPI system exists in order to move messages from one location to another. Therefore, the heart of the system is the MAPI message object. All message objects must have two components-a message header and a message body. The message header contains information used by MAPI to route and track the movement of the message object. The message body contains the actual text message portion of the message object. Even though every message object must have a message body, the body can be left blank. In addition to the two required components, message objects can also have one or more attachments. Attachments can be any valid operating system file such as an ASCII text file, a binary image, or an executable program.

The Message Header

The Message Header contains all the information needed to deliver the associated message body and attachments. Data stored in the message header varies, depending on the messaging service provider. While the exact items and their names and values differ between messaging systems (CMC, MAPI, OLE Messaging), there is a basic core set that appears in all message headers. Examples of basic data items that can be found in a message header are listed in Table 4.1.

Note
The item names given in Table 4.1 do not necessarily correspond to a valid property or variable name in programming code. The actual property names for each item can vary from one code set to another. Also, the order in which these properties appear differs greatly for each MAPI implementation. The chapters following this one focus on different code sets (CMC API, MAPI Controls, OLE Messaging) and detail the exact keywords and property names used to access the items described here.

Table 4.1. Basic data items found in a message header.
Property Name
Type
Description
Recipients Recipients objectE-mail address of the person who will receive the message. This could be a single name, a list of names, or a group name.
Sender AddressEntry objectE-mail address of the person who sent the message.
Subject StringA short text line describing the message.
TimeReceived Variant (Date/Time)The date and time the message was received.
TimeSent Variant (Date/Time)The date and time the message was sent.

Along with this basic set, additional data items may appear or be available to the programmer. These additional items add functionality to the MAPI interface, but because they are not part of the core set, you cannot expect them to be available to you when you write your programs. Table 4.2 contains a list of additional header data items.

Table 4.2. Optional items that may be found in the message header.
Property NameType Description
DeliveryReceipt BooleanFlag that indicates the sender asked for a return receipt message upon either delivery of the message to the recipient or the reading of the message by the recipient.
Importance LongA value that indicates the relative importance of the message. Currently, Microsoft Mail clients recognize three priorities: High, Medium, and Low.
Submitted BooleanFlag that indicates the item has been sent to the recipient.
Sent BooleanRead/write.
Signed BooleanRead/write.
Type StringValue that identifies this message as one of a class of messages. Currently, Microsoft Mail systems recognize the IPM (Interpersonal Message) type for sending messages read by persons. Microsoft has defined the Ipc (Interprocess Communication) type for use between program processes. Other types can be defined and used by other programs.
Unread BooleanFlag that indicates whether the message has been received and/or read by the recipient.

The Message Body

The message body contains the text data sent to the recipient from the sender. For most systems, this is a pure ASCII text message. However, some service providers can handle rich-text format message bodies, which allows for additional information such as font, color, and format codes to be included in the message body (see Figure 4.2).

Figure 4.2 : Using Microsoft Exchange to send a rich-text message.

The availability and support of rich-text message bodies vary between service providers. Some service providers allow you to create rich-text message bodies but translate the information into simple ASCII upon delivery. For example, Microsoft Exchange allows users to build rich-text message bodies but translates that message into simple ASCII text when using the SMTP service provider. All messages received by the Microsoft Mail system are converted into simple text as well. This behavior ensures that the message will be delivered but may result in surprise or even unreadable material at the recipient's end (see Figure 4.3).

Figure 4.3 : Receiving a rich-text message that has been changed to simple ASCII.

Other transport providers may transmit the rich-text and allow the receiving message provider to handle the translation to simple ASCII, if needed. This option allows for the most flexibility but can result in undeliverable messages. For example, Microsoft Exchange users have the option of sending rich-text messages through the CompuServe message transport. The CompuServe transport supports rich-text messages. Rich-text messages sent from one Windows Messaging Client to another by way of the CompuServe transport retain their original layout and look. However, recipients using something other than Microsoft Exchange may see something different. For example, the WinCIM client provided by CompuServe treats rich-text messages as binary attachments to a simple ASCII text message. WinCIM clients would receive the message shown in Figure 4.2 as an attachment to view with Microsoft Word or some other viewer.

If, however, the CompuServe recipient is defined as an Internet user through the CompuServe address (for example, 102461.1267@compuserve.com), the CompuServe message transport reports the message as undeliverable when it is discovered that the message body contains anything other than simple ASCII text (see Figure 4.4).

Figure 4.4 : Reporting an undeliverable rich-text message.

Message Attachments

Message attachments are supported by all forms of Microsoft MAPI. A MAPI attachment can be any data file, of any type (text, binary programs, graphics, and so on). These attachments are sent to the recipient along with the message header and body. Upon receipt of the message, the recipient can, depending on the features of the message client software, view, manipulate, and store the attachments on the local workstation. The MAPI system keeps track of attachments with a set of properties. Table 4.3 lists an example set of attachment properties. The actual properties and their names can differ between program code sets.

Table 4.3. Example MAPI attachment properties.
Property NameType Description
Index LongEach message object can contain more than one attachment. Attachments are numbered starting with 0.
Name StringThe name to display in a list box or in the client message area (for example, "June Sales Report").
Position LongA value that indicates where in the message body the attachment is to be displayed. Microsoft Mail and Windows Messaging clients display an icon representing the attachment within the message body. Other clients may ignore this information, show an icon, or show ASCII text that represents the attachment.
Source StringThe exact filename used by the operating system to locate and identify the attachment (for example, "\\Server1\Data\Accounting\JuneSales.xls").
Type LongA value that indicates the type of attachment. Microsoft defines three attachment types:
Data-A direct file attachment
Embedded OLE-An embedded OLE object
Static OLE-A static OLE object

Attachments can be handled differently by the message transport provider. Microsoft Mail and Windows Messaging clients display attachments within the message body and transport the attachments as part of the message body, too. Microsoft Mail and Microsoft Exchange recipients see the attachment within the message body and can use the mouse to select, view, and save the attachment when desired. Other transports may handle the attachment differently.

SMTP transports will report a message that contains attachments as undeliverable unless the transport supports MIME or some other binary transfer protocol. The Internet transport that ships with the Windows Messaging Client does support MIME protocol.

The CompuServe service provider for Microsoft Exchange will transport the attachments as additional messages addressed to the same recipient. For example, a single ASCII text message with one attachment would be received as two messages when sent via the CompuServe transport.

Note
The CompuServe message transport for Microsoft Exchange supports only attach-ments for native, or CompuServe, addresses. You cannot use the CompuServe transport to send attachments to an SMTP-defined Internet account (such as 102461.1267@compuserve.com).

Storage Folders

MAPI messages can be saved in storage folders. The MAPI model defines several storage folders. Figure 4.5 shows a set of folders as viewed from the Windows Messaging Client.

Figure 4.5 : Viewing the folders from the Windows Messaging Client.

The defined storage folders within MAPI are

Not all implementations of MAPI support all of the folders listed above. For example, the Simple MAPI interface allows access to the Inbox (by way of the .Fetch method of the MAPISession Control) and the Outbox (by way of the .Send method of the MAPISession Control). Simple MAPI allows no other folder access. Programmers cannot inspect the contents of the Sent folder or move messages from the Inbox to other user-defined storage folders.

The OLE Messaging library offers a more complete access to the MAPI storage system. The Inbox and Outbox folders are accessible by name (that is, Session.Inbox and Session.OutBox). The Sent and Deleted folders are available. The OLE MAPI implementation allows access to all folders through the InfoStore object. An Infostore object contains all folder and message objects. All MAPI service providers can implement their own message stores, and a single client can have access to more than one message store at the same time. Therefore, a single MAPI session can involve attaching to several message stores and presenting their contents to the user for handling.

Note
The OLE Messaging library does not allow programmers to create or delete folders from the InfoStore collection. Only the MAPI 1.0 API set available from C++ allows programmers to create and delete folders from the storage set.

The MAPI storage folders are defined as a hierarchy (as seen in Figure 4.5). The MAPI model allows for the creation of multiple levels of the hierarchy at any time. The MAPI model allows for the creation of subfolders at any level and on any folder. For example, the Inbox folder can have several subfolders such as UnRead, Read, Urgent, and Unknown. The addition of subfolders allows users to organize message stores based on use and preference.

The MAPI model defines a handful of properties for storage folders. These properties are available through the OLE Messaging library and C++. Table 4.4 lists some of the more commonly used properties of the storage folder.

Table 4.4. Example MAPI storage folder properties.
Property NameType Description
FolderID StringThis is a string value that uniquely identifies this folder.
Folders Folders collection object This is the set of folder objects contained by the current folder. Any folder can contain one or more sublevel folders.
Messages Messages collection object This is the set of messages stored in this folder.
Name StringA unique user-defined string that identifies the storage folder.
Parent ObjectThis contains the name of the parent folder or InfoStore to which the current folder belongs.

Note
You can find additional information on Folder and InfoStore objects, their properties, and their methods in Chapter 8, "The OLE Messaging Library," and Chapter 9, "Creating a MAPI Mailing List Manager with the OLE Messaging Library."

Physical organization of the storage folders can differ greatly depending on the service provider. For example, the Microsoft Mail Server storage arrangement involves a single directory on the disk that identifies the post office and subsequent directories underneath that correspond to an individual user's InfoStores (and subfolders within the storage). However, the physical organization of storage folders for the Windows Messaging Client that ships with Windows 95 involves a single data file (usually found in \Exchange\mailbox.pst). This single file is used to store all the personal messages maintained on the user's workstation. It is up to the service provider to establish the storage details and to support access to the physical storage using the pre-defined InfoStore, Folder, and Message objects.

Addresses

Addresses are the last class of objects dealt with at the client level. Every electronic message has at least two address objects: the sender object and the recipient object. MAPI allows you to add several recipient address objects to the same message. Each address object has several properties. Table 4.5 shows a set of sample properties for the MAPI Address object.

Table 4.5. MAPI Address object properties.
Property NameType Description
Address StringThis is the unique electronic address for this address object. The combination of the Type property (see below) and the Address property creates the complete MAPI address. Sample address properties are
MikeA@isp.net-Internet address
/MailNet1/PostOfc9/MCA-MS Mail address
DisplayType LongThe MAPI service allows programmers to define addresses by type. This means you can sort or filter messages using the DisplayType property. Sample address types are
mapiUser-Local user
mapiDistList-Distribution list
mapiForum-Public folder
mapiRemoteUser-Remote user
Name StringThis is the name used in the Address book. Usually, this is an easy-to-remember name such as "Fred Smith" or "Mary in Home Office."
Type StringThis value contains the name of the message transport type. This allows MAPI to support the use of external message transport services. Sample address types are
MS:-Microsoft Mail transport
SMTP:-Simple Mail Transport Protocol
MSN:-Microsoft Network transport

MAPI address objects are a part of every MAPI message and are stored in the MAPI address book. You'll learn more about the address book in the following section on MAPI Server objects.

The MAPI Server

The MAPI Server handles all the message traffic generated by MAPI clients. The MAPI Server usually runs on a standalone workstation connected to the network, but this is not a requirement. There are versions of user-level MAPI servers that can be used to handle message services.

Microsoft supports two standalone MAPI servers:

The Microsoft Mail Server runs standalone on both Intel pcs or Apple workstations. It provides direct MAPI services for all connected MAPI users and also provides gateway MAPI services for remote users. The Microsoft Mail Server has, until recently, been Microsoft's primary electronic mail server. Even though Microsoft is stressing the early adoption of the new Microsoft Exchange Server for NT, the Microsoft Mail Server will continue to be the primary mail server for thousands of users. All MAPI Clients can share information with connected Microsoft Mail Servers regardless of the client platform (Win31, WinNT, or Win95).

The Microsoft Exchange Server runs as a service on an NT Server workstation. It provides MAPI services to all MAPI users. Unlike the Microsoft Mail Server, which distinguishes between local and remote users, the Microsoft Exchange Server treats all MAPI users as remote users. This simplifies several aspects of MAPI administration. Unlike the Microsoft Mail Server, which only supports Microsoft Mail format messages, the Microsoft Exchange Server supports multiple message formats and services, including Microsoft Mail. This also means that the administration of gateways and remote transports is quite different for Microsoft Exchange.

Microsoft also supports two peer-to-peer message servers. These servers run on the user's workstation, usually as a part of the MAPI client software. The two client-level MAPI servers provided by Microsoft are

The WorkGroup Post Office runs as a limited version of the Microsoft Mail Server. Clients that use Microsoft's peer-to-peer networking are able to establish a post office on a single workstation and then share the post office directories with other peers on the network. The design and operation are very much like the Microsoft Mail Server system, but it runs on an individual pc. The primary advantage of the peer-to-peer version is that a single user can set up a WorkGroup Post Office and use that as a base for adding remote mail connections and fax support. The main disadvantage of the peer-to-peer client is that users were not able to attach to both the WorkGroup Post Office and an existing Microsoft Mail Server post office.

With the introduction of Windows 95, Microsoft introduced a client version of Microsoft Exchange that provides the same features as the Microsoft Exchange Server version. Users are able to install and share a WorkGroup Post Office and are also able to attach to existing Microsoft Mail post offices. In addition, users can connect using other mail transports as they become available.

Regardless of the actual server application used, the same basic processes must occur for all MAPI server systems. The three main tasks of all MAPI servers are

The next three sections discuss each of these processes in greater detail.

Message Transport

Message Transport is the process of moving messages from one place to another. Under the MAPI model, message transport is a distinct, and often separate, process. MAPI 1.0 allows for the use of external message transports. In other words, programmers can write software that knows how to handle a particular type or types of message formats and register this transport mechanism as part of the MAPI system. This allows third-party vendors to create format-specific transports that can be seamlessly integrated into the MAPI system.

It is the message transport that knows just how to format and, if necessary, pre-process messages for a particular messaging format. The message transport knows exactly what information must be supplied as part of the message header and how it needs to be arranged. The message transport also knows what types of message bodies are supported. For example, SMTP format allows only text message bodies. However, the Microsoft Network message format allows rich-text message bodies. It is the job of the message transport to keep track of these differences, modify the message where appropriate, or reject the message if modification or pre-processing is not possible.

One of the key features of the MAPI model is the provision for multiple message transports within the MAPI system. Once message transports are installed (or registered) with a MAPI client application, they are called into action whenever the pre-defined message type is received by the MAPI client software. Since MAPI is designed to accept the registration of multiple transports, the MAPI Client is potentially capable of handling an unlimited number of vendor-specific message formats.

Note
Message types are stored as part of the address. These types were discussed earlier in this chapter in the "Addresses" section.

Figure 4.6 shows how the multiple message transports are used when messages are received by the MAPI Client.

Figure 4.6 : Handling incoming messages with multiple message transports.

Under the MAPI system, message transports provide another vital service. It is the responsibility of the message transport to enforce any security features required by the message format. For example, the MSN mail transport is responsible for prompting the user for a username and password before attempting to link with the MSN mail system.

It is important to note that the message transport is not responsible for storing the messages that have been received. The transport is only in charge of moving messages from one location to another. Message storage is discussed in the next section.

Message Stores

Message stores are responsible for providing the filing system for the messages received via the message transport. The MAPI model dictates that the message store must be in a hierarchical format that allows multilevel storage. In other words, the system must allow users to create folders to hold messages, and these folders must also be able to hold other folders that hold messages. Under the MAPI model, there is no limit to the number of folder levels that can be defined for a message store (see Figure 4.7).

Figure 4.7 : MAPI message stores are hierarchical filing systems.

Under the MAPI model, storage folders can have properties that control how they are used and how they behave. For example, storage folders can be public or private. Folders can have properties that make the contained messages read-only to prevent modification. The options available depend on the implementation of the message store. In other words, the programmer who designs the message store can establish the scope of storage options and the MAPI Client will comply with those rules.

As in the case with message transports, MAPI clients can access more than one message store. Figure 4.8 shows the Windows Messaging Client that is currently accessing two different message stores. You can see that each store has its own set of folders and its own set of messages.

Figure 4.8 : Accessing multiple message stores at the same time.

The Windows Messaging Client that ships with Microsoft Exchange Server also allows you to create folder column, grouping, sort, and filter rules for personal and public folders. By doing this, you can create storage views that reflect the course of an ongoing discussion and allow for easy search and retrieval of data kept in the message store (see Figure 4.9).

Figure 4.9 : A Microsoft Exchange folder with discussion properties.

Address Books

The last of the main MAPI server objects is the address book. The MAPI address book contains all the directory information about a particular addressee. The book can contain data for individual users or groups of users (a distribution list). The minimum data stored in the address book is the user's display name, the transport type, and the user's e-mail address.

Additional information such as mailing address, telephone number, and other data may be available depending on the design of the address book.

Address books, like the other objects described in this chapter, work independently under the MAPI model. Also, the MAPI client can access more than one address book at a time. This means that several address books of various formats can all be viewed (and used) at the same time when composing messages (see Figure 4.10).

Figure 4.10 : Accessing multiple address books at the same time.

Along with storing addresses, the address book interface also acts to resolve display names used in the MAPI interface with the actual e-mail addresses and transport types for those display names. To do this, MAPI offers a ResolveName service that performs lookups upon request. The ResolveName service is able to look at all address books (regardless of their storage format) in order to locate the proper e-mail address.

Users are also able to designate one of the address books as the default or personal address book. This is the first address book in which new addresses are stored and the first address book that is checked when resolving a display name. The Windows Messaging Client and the Microsoft Mail client both ship with default personal address books. The Windows Messaging Client allows users to add new address books and designate their own personal address book container.

The MAPI Spooler

The MAPI Spooler is a special process that interacts with both message stores and message transports. It is the spooler's job to route messages from the client to the proper transport and from the transport to the client. The spooler is the direct link between the client and the transport. All messages go through the MAPI Spooler.

Note
Actually there are some cases in which a message moves directly from the message store to the message transport. This occurs when service providers offer both message store and message transport. E-mail service providers that offer these features are known as tightly coupled service providers.

Figure 4.11 illustrates the different paths messages can take when the MAPI Spooler is used.

Figure 4.11 : The MAPI Spooler passes messages between the message store and the message transport.

As each message is moved from the message store (the "outbox") to the transport, the MAPI Spooler checks the address type to see which transport should be used. Once this is determined, the spooler notifies the transport and attempts to pass the message from the message store to the message transport. If the transport is not currently available, the MAPI Spooler holds onto the message until the transport is free to accept messages. This allows transport providers to act as remote connections without any additional programming or addressing on the client side.

Note
In fact, the implementation used in the Microsoft Exchange version of MAPI treats all connections as if they were remote-even when the message is moved from one user's Microsoft Exchange outbox to another Microsoft Exchange user's inbox on the same network.

In the case of messages that move along a constantly connected transport (that is, between two addresses on the same Microsoft Exchange Server), the spooler notifies the transport (Microsoft Exchange) and the transport accepts the message almost immediately. Often the user is not aware of any delay in the handling of the message.

In the case of messages that move from the Windows Messaging Client by way of an SMTP transport through a dial-up connection to the Internet, the MAPI Spooler holds onto the message until the user connects to the Internet account through Win95 Dial-Up Networking. Once the connection is made, the MAPI Spooler sends all local messages on to the Internet mail server, retrieves any waiting mail from the mail server, and passes these new messages to the appropriate message store.

The MAPI Spooler is also able to move a single message to several recipients when some of those recipients are not using the same message transport. For example, users can build distribution lists that contain names of users on the local Microsoft Exchange Server, users who have addresses on a local Microsoft Mail Server, and users who can only be contacted through a fax address. When the message is sent, it moves from the message store to the spooler, which then sorts out all the transports needed and passes the messages on to the correct transports at the first available moment.

The MAPI Spooler is also responsible for marking messages as read or unread, notifying the sender when a message has been successfully passed to the transport, and, when requested, notifying the sender when the recipient has received (or read) the message. The MAPI Spooler also reports when messages cannot be sent due to unavailable transports or other problems.

Summary

In this chapter, you learned about the general architecture of the MAPI system. You learned that there are two main components to the system:

You learned that the MAPI Client resides on the user's desktop and handles three main MAPI objects:

This chapter also reviewed the basic properties and features of MAPI messages, including message headers, folders, and address objects.

You learned that the MAPI Server usually resides on a standalone workstation connected to the network (although not always). Like the MAPI Client, the MAPI Server handles three main objects:

You learned that the MAPI model allows users to use multiple versions of message transports (such as Microsoft Exchange Server messages and SMTP Internet messages), message storage, and address books. You also learned about the MAPI Spooler. The MAPI Spooler is the process that moves items from the message store to the appropriate provider.

Now that you know the basic architecture of the MAPI system, it's time to build some applications that use the system. In the next chapter, you'll learn how to use the Microsoft Exchange Forms Designer to build MAPI-enabled applications that work within the Microsoft Exchange interface.