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