MailFirstEx

This function, an extension of MailFirst, retrieves the first of a specified type of message from a folder in the message store and operates in a multiple folder hierarchy environment.

At a Glance

Syntax

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

Parameters

hMail

[in] Handle to the mail context. The MailOpen function creates this handle.

pmm

[in/out] Pointer to the MailMsg structure. The dwFlags member of MailMsg determines what type of message this function should retrieve and how much of the message to return.

This function returns the specified message in MailMsg. The following message flags determine how much of the message this function retrieves:

MAIL_GET_FLAGS

The MailGetEx function returns only the flags and the object identifier, including the dwMsgId, dwFlags, dwMsgLen, wBodyLen, and ftDate MailMsg members. MAIL_GET_FLAGS also instructs MailGetEx to return the pfid and pfidTarget parameters.

MailGetEx does not allocate any memory for the message body.

MAIL_GET_BODY

MailGetEx loads the entire message into memory, and creates and allocates memory from a private heap for the message.

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

pfid

[in/out] Pointer to the folder identifier of the folder to search in. This function ignores this parameter if the MAIL_FOLDER_ANY flag is set in the dwFlags member of MailMsg. If you set the MAIL_FOLDER_ANY flag, pfid returns the message folder identifier of the first message found that matches the description of the flags set in MailMsg.

pfidTarget

[in/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 the MailMsg structure. Set pfidTarget to NULL if you do not need the target folder identifier.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

Remarks

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 search a folder for 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 the folder 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.