MailNextEx

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

At a Glance

Syntax

BOOL MailNextEx (HANDLE hMail, MailMsg* pmm, FID fid, FID fidTarget,
BOOL fDoAll);

Parameters

hMail

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

pmm

[in/out] Pointer to the MailMsg structure. The dwFlags member of MailMsg is a combination of folder, status, and message flags. The folder flag determines which folder the message is in. The status flags determine what type of message this function should retrieve. The message flags determine how much of the message this function returns.

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. The pfid parameter returns the message folder identifier.

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 MailMsg. 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

The flags of MailMsg must be set prior to each call to this function. This is because each call to MailFirstEx, MailGetEx, or this function returns the flags of the message as it is stored in the database.

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 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.