MailNext

After a call to MailFirst, the MailNext function retrieves the next of a specified type of mail entry from the message store.

Syntax

BOOL MailNext (HANDLE hMail, MailMsg* pmm);

At a Glance

Header file:	Msgstore.h
Platforms:	H/PC
Versions:	1.0 and later

Parameters

hMail: Handle to the mail context. This handle is created by the MailOpen function.
pmm: Pointer to the MailMsg structure that contains the flags determining which folder the message is in, what type of message it is, and how much of the message to retrieve. The mail flag value in the dwFlags member of the structure is a combination of folder, status, and message flags. The folder flag determines which folder the entry will be retrieved from. One folder flag can be combined with any number of status flags and message flags. The status flags determine what type of message to retrieve, and the message flags determine how much of the message is returned.
When MailNext returns, this structure contains the message retrieved from the message store. Two of the message flags determine how much of the message to retrieve. If MAIL_GET_FLAGS is set, only the flags and the object identifier are returned. Using this option does not require any memory to be allocated for the message. If the MAIL_GET_BODY flag is set, the entire message is loaded into memory. This requires the system to allocate memory from the global heap. If neither of these flags is set, all of the message except the body is retrieved. Memory for this option is allocated from the private heap. To free memory allocated by MailNext use the MailFree function.

Return Values

This function returns TRUE if successful; FALSE if it fails. To get extended error information, use MailError or MailErrorMsg.

Remarks

The flags of the MailMsg structure must be set prior to each call to MailNext because each call to MailFirst, MailGet, or MailNext returns the flags of the message as it is stored in the database.

Changing the values of the MailMsg variable does not affect the message store until the message is reinserted by calling the MailUpdate function.