Introduction to MAPI in Pocket PC 2002 C++ Applications, Part 1

 

Microsoft Corporation

June 2002

Summary: Because the Pocket PC 2002 SDK removes the MsgStore APIs, applications based on Pocket PC 2002 must now use MAPI to interact with the user's e-mail subsystem. This can be quite daunting at first but don't despair, help has arrived! This article deals with the basic operation of MAPI (initializing the API and sending mail). (2 printed pages)

Applies to:

   Microsoft® Windows® Powered Pocket PC 2002
   Microsoft eMbedded Visual C++ version 3.0
   Pocket PC 2002 SDK
   VOMAPI classes from Virtual Office Systems Web site (a free download)

Gotchas

If you're used to MAPI development on the desktop, be prepared to find that many of the MAPI interfaces and utility APIs that you may have depended on for that platform will not be implemented in CEMAPI.

Languages supported

Any language supported by Microsoft® eMbedded Visual C++® 3.0. Screenshots in U.S. English.

Contents

MAPI Concepts
Initializing MAPI
Sending Mail
Conclusion
Further Reading

MAPI Concepts

Strictly speaking, MAPI isn't as much of an API as most other APIs. Rather, it is a collection of COM objects that act as mediators between applications and "back end" messaging systems, such as Microsoft Exchange and SMTP/POP3 (Internet) e-mail.

At the root level, MAPI consists of a Session object, which contains a collection called the Message Stores Table. The Message Stores Table in turn contains one or more Message Store objects, which contain Folder objects. In Folder objects you'll find Message objects. As you can readily tell, hierarchy is key to MAPI structure, as are collection objects. The figure below shows the basic object hierarchy in the MAPI subsystem.

Figure 1. MAPI object hierarchy

Initializing MAPI

Getting MAPI up and running is relatively straightforward. In the sample project, I wrapped the global initialization and termination in a separate object class named CVOMAPIGlobal, and declared a static instance of this object in the CVOMAPI class. By doing this the global initialization occurs at application load, and the termination takes place at application shutdown, when the global object's destructor is called.

  • Call the CoInitializeEx() Microsoft Win32® API to initialize the COM subsystem.
  • Call the MAPIInitialize() function (for now, just pass NULL as the parameter. We will get into this more in the third article in this series).
  • Call MAPILogonEx() to obtain an interface pointer to the MAPI Session object.
  • Obtain a handle to the Message Stores Table using the GetMsgStoresTable method of the IMAPISession object. This table will contain a list of all available message stores.
  • Alternately, you can call the OpenMsgStore method of the IMAPISession object passing NULL or 0 for all parameters except the output (message store) parameter. This will open the default message store.

Sending Mail

Now that you have MAPI initialized, you can send mail by creating a MAPI Message object. Message details such as the subject, the body, and the recipients are all stored as properties of the Message object. You can see the full process in the sample code by looking at the CVOMAPI::SendMessage() method. Here are the steps involved:

  1. Obtain a pointer to the MAPI folder you want the message to be created in (or call the OpenMsgStore method of the IMAPISession object to obtain the default folder).
  2. Call the CreateMessage method of the folder object to create the instance of the message object.
  3. For each recipient, populate an ADRENTRY structure with the following properties for the recipient: PR_RECIPIENT_TYPE, PR_ADDRTYPE, and PR_EMAIL_ADDRESS.
  4. The entries can either be added individually or as an array using the ModifyRecipients method of the MAPI Message object (passing MODRECIP_ADD as the first parameter).
  5. Assign the subject to the message by setting the Message object's PR_SUBJECT property.
  6. Obtain a pointer to the message body's stream interface by calling the OpenProperty method of the MAPI message object.
  7. Assign the body to the message by calling the Write method of the stream interface.
  8. Call the SubmitMessage method of the MAPI Message object.

Conclusion

Although you will probably be overwhelmed by the sheer amount of information in MAPI when you first look at the documentation, by focusing just on the areas that your application uses you will find that the interface is manageable, and yet powerful enough to later add new messaging capabilities to your application.

Further Reading

To learn more, continue on to part two of this three-part series.