Programming with MAPI

All MAPI interfaces are available in both 16- and 32-bit versions to support the Windows family. You can call MAPI functions from C or C++ programs through scripting packages like Microsoft Visual Basic or by using the macro languages in Microsoft Excel or Word for Windows.

The MAPI programming architecture includes the session, the message store, and the address book. MAPI clients must establish sessions with the messaging subsystem before they can interact with the messaging stores and address books. You use the MAPILogon function to log clients on to the messaging system and authenticate their identity to the messaging system. You can create custom dialog boxes for the log-on process, or you can use the standard MAPI log-on dialog box.

Logging on generates a session handle that applications use to interact with the MAPI envi ronment. A session handle is a pointer to a session object, which supports the IMAPISession interface. You use IMAPISession methods to manage and find objects in the MAPI environment.

An example is IMAPISession::OpenAddressBook, which opens the address book. It is possible for a single client to acquire handles to two different session objects and open two different message stores. In this way, clients can copy data between message stores in different environments.

After log-on and retrieval of a handle to a session object, the application can access message stores. You use the IMAPISession::GetMsgStoresTable method to get information about available message stores. The table that this method returns contains row and column information. The rows list message stores. The columns list information about the message stores, such as entry ID (i.e., unique reference), the name of the provider that handles the message store, and whether the message store is the default.

The IMAPITable interface is used to retrieve information from the message-stores table. For example, IMAPITable::SetColumns specifies a column,

and IMAPITable::QueryRows returns the data in a specified number of rows, starting with the current column. To actually open a message store, you pass its entry ID to the IMAPISession::OpenMsgStore method. Once a message store is open, you use the IMAPIMsgStore interface to browse its folder hierarchy.

You create and manage folders with the IFolder interface. The functions of the interface become available when you create or open a folder object. For example, IFolder::GetContentsTable returns a pointer to a table of summary information. IFolder::GetHierarchyTable returns a table object with information about the child folders of the current folder. There are also functions for performing management on folder objects and messages in folders and for reading or setting search criteria.

Address Information

MAPI address books provide message address information and hide the differences in addressing schemes used by the different back-end messaging services. Programs can access address books without user intervention, or you give users access through the common dialog boxes provided with MAPI. The address-book dialog boxes let users pick ``human-readable'' names from a list, which are converted in the background to internally used messaging addresses. Address books, like MAPI message stores, are hierarchical objects. Objects in the address book (i.e., containers, mail users, and distribution lists) are accessed with unique entry IDs.

You open an address book by calling the OpenAddressBook method on the session object. A pointer to an address-book object is returned that supports IAddrBook, which is a high-level interface to the address book. It supports operations like displaying the address-book dialog box, opening containers in the address book, and resolving friendly names with E-mail names. You can view the internal organization and structure of an open address book w ith IABContainer::GetHierarchyTable. This returns a table that you can examine with the IMAPITable interface. MAPI provides other interfaces for creating containers in address books and adding recipients in the container.

Messages, attachments, and other MAPI objects are principally composed of data called properties. A property is a data structure that contains a unique identifier, information about the data type, and the value of the data. Applications use the IMAPIProp interface to read, write, and modify object properties.

Common MAPI properties include the subject line of a message, user names, and the body of an attachment. Properties are values read by the recipient or the transport that handles the delivery of the message. Every property accessed by object methods has a unique name. For example, every MAPI object has a property called PR_OBJECT_TYPE that describes the type of object it is.

Finally, messages are created in folders with IFolder::CreateMessage. This returns a pointer to a message object. Message properties are set using IMAPIProp::SetProps. Message properties include the icon associated with the message, text that appears in the message's Subject field, and the text that makes up the body of the message.

So that the user can address the message, IAddrBook::Address is called, which returns a list of recipients that the user selected from the address-book dialog box. A pointer to this recipient list is then passed to the message object using IMessage::Modify Recipients. When the message is complete, it is sent with IMessage::SubmitMessage. This saves all changes and marks the message for sending. At this point, the underlying messaging system takes over and delivers the message.