MAPI Overview

The Mail API on Pocket PC provides you with a set of COM interfaces that are used primarily to work with the data associated with e-mail. This includes the capability to create new messages, manipulate e-mail folders, read existing messages and attachments, and receive notifications when e-mail activity occurs. In order to send and receive messages, most applications use an existing e-mail transport, an interface that enables communication from a device to a server; and an existing e-mail application (such as Inbox) for general communication needs. How an application uses MAPI depends on what it is trying to accomplish with e-mail.

Three basic categories of applications use MAPI:

As a developer, you might have already begun to recognize the MAPI acronym. The Mail API that is available on a Pocket PC device is a "slimmed down" version of the MAPI found on a normal Windows desktop machine. If you are already familiar with the MAPI objects and interfaces in Windows XP, then be forewarned: Many of the objects and interfaces found on the desktop are not present or implemented on Pocket PC.

Figure 11.2 illustrates the object model that MAPI uses to expose e-mail that has been stored on the device.

Figure 11.3 illustrates how the MAPI component object architecture relates to the Pocket PC Inbox:

The Mail API Object Model consists of the following interfaces:

• The parent object that you use when writing software that uses MAPI is the IMAPISession interface. This is used to initialize MAPI, and enables you to log on to a message store.

• The IMsgStore interface is used to provide access to the file storage associated with a specific e-mail transport.

• The IMAPIFolder interface is used to access messages and subfolders contained within a message store.

• The IMAPIContainer interface is a parent interface that is used to handle operations on container objects such as folders. The IMAPIFolder interface is derived from IMAPIContainer.

• The IMAPITable interface is used to view collections of MAPI objects. For example, a MAPI folder will contain a table of messages.

• The IMAPIProp interface is used to set and retrieve MAPI object properties.

• The IMAPIAdviceSink interface is used for handling MAPI notification messages.

• The IMessage interface is used to handle individual e-mail messages.

• The IAttach interface is used to handle e-mail message attachments.

In addition, MAPI provides you with several functions and macros to simplify the use of the various MAPI data types. Other functions enable you to log on to a MAPI session, and perform memory management on data objects that MAPI returns to you.

Before learning how to write MAPI applications, let's take a quick look at two additional support interfaces that MAPI uses: IMailSyncHandler and IMailSyncCallback.

A Word about MAPI Transports

You can use several MAPI transports that ship with Pocket PC to send and receive e-mail messages:

• The ActiveSync transport synchronizes e-mail data with a desktop version of Outlook.

• The POP3/SMTP transport receives e-mail over the Post Office Protocol (see RFC 1225) and sends e-mail over the Simple Mail Transfer Protocol (see RFC 821).

• The SMS transport is used on Pocket PC Phone Edition devices to send and receive e-mail over the Short Message Service.

• The IMAP4 transport is used to send and receive messages over the Internet Message Access Protocol version 4 (see RFC 2060).

Each e-mail transport implements the IMailSyncHandler interface. This interface is used by e-mail client applications to directly communicate with the transport for performing synchronization with a server. Although developing new mail transports is beyond the scope of this chapter, I have included a list of the methods that it supports.

Table 11.1 describes the methods supported by the IMailSyncHandler interface.

Before a transport can be used by a mail application, it needs to be properly registered in the Pocket PC registry in the following location:

HKEY_LOCAL_MACHINE\Software\Microsoft\Inbox\Svc\Transport Name

Each transport name represents an installed mail transport. Table 11.2 describes the values that need to be configured for each transport.

The following example shows how you can enumerate the e-mail transports that are installed on a Pocket PC device:

// Enumerate installed e-mail transports
// Step 1. Open a handle to the transports in the registry
HKEY hKey = NULL;
DWORD dwValType = 0, dwSize = sizeof(DWORD);
if(RegOpenKeyEx(HKEY_LOCAL_MACHINE, TEXT("Software\\
  Microsoft\\Inbox\\Svc"), 0, 0, &hKey) != ERROR_SUCCESS)
   return FALSE;

// Step 2. Enumerate the keys - each will represent a
// transport
TCHAR tchTransName[256] = TEXT("\0");
DWORD dwNameSize = 255;
int nIndex = 0;
long lResult;

do {
   lResult = RegEnumKeyEx(hKey, nIndex, tchTransName,
      &dwNameSize, NULL, NULL, NULL, NULL);

   if(lResult == ERROR_NO_MORE_ITEMS)
     break;

   // Got the transport name, do something with it. For this
   // example, we'll just print out the installed transports.

      MessageBox(NULL, tchTransName, TEXT("Installed
     Transports"), MB_OK);

      nIndex++;
      dwNameSize = 255;
      memset(tchTransName, 0, 256*sizeof(TCHAR));
   } while(1);

   // Step 3. Close up the registry
   if(hKey)
      RegCloseKey(hKey);

Building E-mail Client Applications

Another topic that should be briefly covered is the building of new client e-mail applications. This section does not provide detailed information, however, because the Pocket PC Logo Certification Guidelines specify that although application developers should use MAPI for working with the universal e-mail stores, they should not replicate the functionality of Pocket Inbox. However, for the sake of completeness, let's take a quick look at the IMailSyncCallback interface.

The IMailSyncCallback interface needs to be implemented by an e-mail client application in order to enable a mail transport to communicate with it. The interface needs to expose the methods described in Table 11.3.