MailGetEx

This function, an extension of MailGet, retrieves a mail entry from the message store and operates in a multiple folder hierarchy environment.

At a Glance

Header file:	Msgstor2.h
Platforms:	H/PC 3.0
Windows CE versions:	2.10 and later

Syntax

BOOL MailGetEx (HANDLE hMail, MailMsg* pmm, FID* pfid,
FID* pfidTarget);

Parameters

hMail

[in] Handle to the mail context. This handle is created by the MailOpen function.

pmm

[in/out] Pointer to the MailMsg structure that contains the object identifier of the message to be retrieved. MailMsg also contains flags that determine how much of the message this function retrieves.

When this function returns, MailMsg contains the message retrieved from the message store. Setting the following two message flags in the dwFlags member of MailMsg determine how much of the message this function retrieves:

MAIL_GET_FLAGS: This function returns the oid, dwFlags, dwMsgId, dwFlags, dwMsgLen, wBodyLen, and ftDate parameters of MailMsg. MAIL_GET_FLAGS also instructs this function to return the pfid and pfidTarget parameters.
This function does not allocate any memory for the message body.
MAIL_GET_BODY: This function loads the entire message into memory and creates and allocates memory from a private heap for the message.

If you set neither of these flags, this function retrieves only the full message header and allocates memory from a private heap.

pfid

[out] Pointer to the folder identifier of the folder that the message is currently in.

pfidTarget

[out] Pointer to the target folder identifier of a Copy or Move command. This parameter is only valid if the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flags are set in the dwFlags member of MailMsg. Set pfidTarget to NULL if you do not need the target folder identifier.

Return Values

TRUE indicates success. FALSE indicates failure. Call the function MailError or MailErrorMsg for extended error information.

Remarks

This function retrieves the mail message based on the value of the oid member the MailMsg.

Once this function has retrieved a message, you can modify the values returned in MailMsg. However, changing the values of MailMsg does not affect the message store until a call to the function MailUpdateEx reinserts MailMsg into the message store.

When using this function to retrieve a message, treat any message that has the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag set as being located in the pfidTarget folder. This folder may differ from that indicated by fid because a client can attempt to move or copy a message from one folder to another while the client is not connected to a mail server. If this happens, the OS sets the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag in MailMsg. MailUpdateEx saves the target folder, along with MailMsg, in the store. When the device connects to the mail server, the Inbox client performs the move or copy on the server, then uses MailUpdateEx to clear the existing flag from MailMsg and to set the value of fid to the new target folder.

To free memory allocated by this function, use the function MailFree.