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

  • Article

 

Microsoft Corporation

June 2002

Summary: This article completes the three-part MAPI series, covering attachments on both incoming and outgoing messages. Part 1 covered initializing MAPI and sending mail using the MAPI functions and/or the CVOMAPI classes. Part 2 dealt with reading messages and using message stores other than the default (ActiveSync) message store. (3 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

As mentioned in Part I of this series, there are many parts of MAPI that are not fully implemented on the Pocket PC 2002 MAPI, such as the address book, most query filters, and most attachment types.

Languages supported

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

Contents

MAPI Attachments
Sending Attachments
Reading Attachments
Conclusion

MAPI Attachments

MAPI messages can have one or more attachments. Any type of file object can be attached to a MAPI message. By setting (or reading) the IAttach interface properties the application can define the contents of the attachment. To create a message with an attachment using the sample project:

  1. Select MAPI…Send Mail from the menu. The Send Mail dialog will appear as shown in the figure.
  2. Enter the To, Subject, and Body data.
  3. Click the browse " … " button beside the attachment name.
  4. Select a file to attach to the message.
  5. Click the OK button.

Figure 1. Send Mail dialog in MAPI2 sample project

The sample project only allows a single attachment to be specified, but multiple attachments can be created using the same technique.

Sending Attachments

Sending attachments is shown in the sample project in the CVOMAPI::SetProperties() method. Perform the following steps:

  1. The CreateAttach() method of the IMessage interface is called to create the actual attachment. When it is created, the attachment contents are empty. This will give you an IAttach object's interface pointer.
  2. Set the IAttach object's PR_ATTACH_METHOD property to ATTACH_BY_VALUE (the only attach method supported by CE MAPI).
  3. Set the IAttach object's PR_ATTACH_DATA_BIN property to the contents of the attachment. Since this is a binary type variant, you will need to set both the cb (size) and lpb (buffer) elements. Allocate the memory for the lpb buffer using MAPIAllocateBuffer().
  4. Set the IAttach object's PR_ATTACH_FILENAME property to the display name of the object. The extension on this file name should match the original file's extension so that the icon can be rendered correctly in the e-mail software.
  5. Set the IAttach object's PR_ATTACH_SIZE property to the size of all properties for the attachment. This is optional and is used primarily for estimating the size of the attachment without opening the attachment (for example, if the mail application will display the size of each attachment, it could use this property instead of needing to retrieve the entire binary PR_ATTACH_DATA_BIN property just to tell its size).
  6. Although the documentation says that the SaveChanges() method needs to be called for both the attachment and the message, this is not true under the Microsoft Pocket PC 2002 platform; the changes save automatically.

Reading Attachments

Reading attachments is very similar to generating them, except that the properties are of course not created by your application, as they are already part of the incoming message. To read an attachment:

  1. Call the IMessage::GetAttachmentTable() method to obtain an IMAPITable interface pointer to the table of attachments for the message.
  2. Call the IMAPITable::SetColumns() method to define which properties on the attachment you want to retrieve. You should set at least PR_ATTACH_SIZE, PR_ATTACH_NUM and PR_ATTACH_FILENAME to list the attachments.
  3. Call the IMAPITable::QueryAllRows() method to obtain the actual rows.
  4. For each message, call the IMessage::OpenAttach() method passing the PR_ATTACH_NUM property for each attachment.
  5. Use the IMAPIProp::OpenProperty() method to obtain the contents of the PR_ATTACH_DATA_BIN property. As with the PR_BODY property discussed in Part 2 of this MAPI series, the contents of this property might exceed the maximum size of a property in MAPI (currently around 4 KB).
  6. Remember to release any IAttach interface pointers using the Release() function.

Conclusion

With attachments, your application can both send and receive binary data using e-mail as its transport mechanism. As more fully wireless Pocket PC 2002 devices are introduced, passing information back and forth between other users through e-mail will become commonplace, as will applications that generate and interpret the data in the attachments.