Messages

MAPI Message objects are contained in folders that are part of a message store, each representing an individual e-mail message. The messaging system provides you with complete functionality to create, send, read, move, and delete messages. In addition to the actual message body, an e-mail message can have one or more attachments associated with it. An attachment is a blob of binary data, such as a picture or sound file that is transmitted as part of the message.

Messages in MAPI are represented by the IMessage interface, which supports the methods described in Table 11.19.

Table 11.19. IMessage Methods

Method

Description

CreateAttach()

Creates a new message attachment and returns a new IAttach interface

DeleteAttach()

Deletes a message attachment

GetAttachmentTable()

Returns an IMAPITable interface that represents the message attachments

GetRecipientTable()

Returns an IMAPITable interface that represents the message recipients

ModifyRecipients()

Replaces the message recipient address list with a new one

OpenAttach()

Opens a message attachment and returns its IAttach interface

SubmitMessage()

Saves all changes and marks the message to be sent by the message transport

The IMessage interface is also derived from the IMAPIProp interface and supports the properties described in Table 11.20.

Table 11.20. IMessage Properties

Property Tag

Property Type

Description

PR_ADDRTYPE

PT_TSTRING

The e-mail address type. SMTP is currently the only address type supported on Pocket PC.

PR_BODY

PT_TSTRING

The body of the e-mail message.

PR_CE_XHEADERS

PT_TSTRING

The entire string of the message x-headers.

PR_CONTENT_LENGTH_EX

PT_LONG

The full size of the message on the server.

PR_EMAIL_ADDRESS

PT_TSTRING

The actual e-mail address.

PR_ENTRYID

PT_BINARY

The object's entry identifier.

PR_HASATTACH

PT_BOOLEAN

Specifies whether the e-mail message has an attachment table.

PR_LAST_MODIFICATION_TIME

PT_SYSTIME

The last date and time the object was modified.

PR_MESSAGE_CLASS

PT_TSTRING

The type of message.

PR_MESSAGE_DELIVERY_TIME

PT_SYSTIME

The date and time that the message was delivered.

PR_MESSAGE_FLAGS

PT_LONG

Flags for the message. Can be set to MSGFLAG_READ to mark the message as read, or MSGFLAG_UNSENT to specify that the message is being written.

PR_MESSAGE_SIZE

PT_LONG

The size of the entire message, including headers and attachments.

PR_NULL

PT_NULL

A null value.

PR_OBJECT_TYPE

PT_LONG

The type of object.

PR_PARENT_ENTRYID

PT_BINARY

The parent object's entry identifier.

PR_SENDER_EMAIL_ADDRESS

PT_TSTRING

E-mail address of the sender of the message.

PR_SENDER_NAME

PT_TSTRING

Name of the sender of the message.

PR_SUBJECT

PT_TSTRING

Subject of the message.

PR_SUBJECT_PREFIX

PT_TSTRING

Prefix of the message subject, such as Re: for a reply, or Fw: for a forwarded e-mail message.

To retrieve a list of messages stored in a particular folder, get the folder's content table using the IMAPIContainer::GetContentsTable() function, which is defined as follows:

HRESULT IMAPIContainer::GetContentsTable(ULONG ulFlags,
   LPMAPITABLE *lppTable);

The first parameter is ignored and should be set to 0. The lppTable parameter will point to the MAPI table interface for the list of messages.

As with any other MAPI object, you can get the interface pointer to an individual message by using the IMAPIContainer::OpenEntry() function once you have its ENTRYID property.

Message Address Lists

Every e-mail message, whether incoming or outgoing, needs a list of recipients for whom the message is intended. This includes both new messages that you are creating (using the IMAPIFolder::CreateMessage() function) and messages that already exist (by getting the pointer to the IMessage interface using the IMAPIContainer::OpenEntry() function). Either way, once you have the pointer to an IMessage interface, you can use the IMessage::ModifyRecipients() and IMessage::GetRecipientTable() functions to add or manipulate message recipients.

Message recipients are stored in MAPI using the ADRLIST structure, which contains an array of ADRENTRY structures. It is defined as follows:

typedef struct _ADRLIST {
   ULONG cEntries;
   ADRENTRY aEntries[MAPI_DIM];
} ADRLIST, FAR *LPADRLIST;

The cEntries field contains the number of ADRENTRY structures in the array, specified by the aEntries field.

An ADRENTRY structure contains a list of properties that belong to a recipient. Typically, when creating an e-mail recipient, you need to configure only the PR_ADDRTYPE and PR_EMAIL_ADDRESS properties. The structure has the following definition:

typedef struct _ADRENTRY {
   ULONG ulReserved1;
   ULONG cValues;
   LPSPropValue rgPropVals;
} ADRENTRY, FAR *LPADRENTRY;

The first field, ulReserved1, is not used and must be set to 0. The cValues field contains the number of property values that are specified in rgPropVals. The rgPropVals field points to an SPropValue array that contains the property values for the specific recipient.

Table 11.21 describes the macros that MAPI provides to help you efficiently work with the ADRLIST structure.

Table 11.21. ADRLIST Macro Functions

Macro

Description

CbADRLIST(_lpadrlist)

Calculates the number of bytes of an existing ADRLIST structure

CbNewADRLIST(_centries)

Calculates the number of bytes for a new ADRLIST structure

SizedADRLIST(_centries,_name)

Creates a named ADRLIST structure for a specific number of ADRENTRY structures