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:

  1. Generic applications that require e-mail integration. These applications use MAPI to send and read messages. For example, the Pocket Outlook Calendar uses MAPI to send e-mail messages for a meeting request.

  2. MAPI Transports. Another type of MAPI object is a mail transport, which provides the communications functionality to connect a device with a server. Applications such as an e-mail client (e.g., Pocket Inbox) directly use MAPI transports to synchronize with a mail server. An example of a MAPI transport that ships with Pocket PC is POP3.

  3. E-mail clients. E-mail clients use MAPI transports along with the other MAPI interfaces to create e-mail messages, synchronize with a server, and so on. The Pocket Inbox is an e-mail client application.

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.

NOTE:

The MAPI interfaces are new to Pocket PC 2002. Previous versions of Windows CE and Pocket PC use the CE Message Store APIs, which are no longer supported 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.2. Pocket PC Mail API Object Model

graphics/11fig02.gif

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

Figure 11.3. Breakdown of the Pocket PC Inbox

graphics/11fig03.gif

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.

Table 11.1. IMailSyncHandler Methods

Method

Description

Connect()

Requests the transport to connect to a server

DecodeEvent()

Decodes a logged event to a string

Disconnect()

Requests the transport to disconnect from a server

DoProperties()

Reserved

FolderOptions()

Enumeration used by IMailSyncHandler::SetFolderOptions to set various folder options

GetCapability()

Gets the setting for a specific transport capability

GetFolderHierarchy()

Queries the transport for the folder hierarchy

Initialize()

Initializes the transport

Install()

Configures the transport

SetCapability()

Sets a specific transport capability setting

SetFolderOptions()

Sets an option on a specific transport folder

Shutdown()

Shuts down the transport

Synchronize()

Places a synchronization request with the transport

UnInstall()

Removes the transport

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.

Table 11.2. Registry Settings for a Mail Transport

Name

Type

Description

DLL

String

Name and path to the transport DLL

Name

String

Name to be displayed for the transport

Port

DWORD

Server port to connect with

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.

Table 11.3. IMailSyncCallback Methods

Method

Description

AllocateMem()

Allocates memory for the calling message transport

DisplayMessageBox()

Reserved

FreeMem()

Frees memory that has been allocated by a call to the IMailSyncCallback::AllocateMem() function

GetGlobalSetting()

Gets the value for a setting from the e-mail application that has implemented the IMailSyncCallback interface

LogEvent()

Logs an error event

Progress()

Progress notification for synchronization events in the transport

RequestCredentials()

Request from the transport about user credentials

RequestSync()

Reserved