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