MailFirst

The MailFirst function retrieves the first of a specified type of message from a folder in the message store.

Syntax

BOOL MailFirst (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 MailFirst 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 this function, 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 MailFirst function obtains the information and fills a MailMsg structure variable with the values retrieved from the message store. Changing the values in MailMsg does not affect the message store until it is reinserted by a call to the MailUpdate function.