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. 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
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
The Mail API Object Model consists of the following interfaces:
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 TransportsYou can use several MAPI transports that ship with Pocket PC to send and receive e-mail messages:
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 ApplicationsAnother 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.
|