INT WINAPI ImapGetMessage(
	HCLIENT hClient,
	UINT nMessageId,
	UINT nMessagePart,
	LPVOID lpvMessage,
	LPDWORD lpdwLength,
	DWORD dwOptions
);

The ImapGetMessage function retrieves a message from the server.

Parameters

hClient

Handle to the client session.

nMessageId

Number of message to retrieve from the server. This value must be greater than zero. The first message in the mailbox is message number one.

nMessagePart

The message part that will be retrieved. A value of zero specifies that the complete message should be returned. If the message is a multipart MIME message, message parts start with a value of one.

lpvMessage

A pointer to a byte buffer which will contain the data transferred from the server, or a pointer to a global memory handle which will reference the data when the function returns.

lpdwLength

A pointer to an unsigned long integer which should be initialized to the maximum number of bytes that can be copied to the buffer specified by the lpvMessage parameter. If the lpvMessage parameter points to a global memory handle, the length value should be initialized to zero. When the function returns, this value will be updated with the actual length of the message that was downloaded.

dwOptions

An unsigned integer value which specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:

Constant	Description
IMAP_SECTION_DEFAULT	All headers and the complete body of the specified messager or message part are to be retrieved. The client application is responsible for parsing the header block. If the message is a MIME multipart message and the complete message is returned, the application is responsible for parsing the individual message parts if necessary.
IMAP_SECTION_HEADER	All headers for the specified message or message part are to be retrieved. The client application is responsible for parsing the header block.
IMAP_SECTION_MIMEHEADER	The MIME headers for the specified message or message are to be retrieved. Only those header fields which are used in MIME messages, such as Content-Type will be returned to the client. This is typically useful when processing the header for a multipart message which contains file attachments. The client application is responsible for parsing the header block.
IMAP_SECTION_BODY	The body of the specified message or message part is to be retrieved. For a MIME formatted message, this may include data that is uuencoded or base64 encoded. The application is responsible for decoding this data.
IMAP_SECTION_PREVIEW	The message header or body is being previewed and should not be marked as read by the server. This prevents the message from having the IMAP_FLAG_SEEN flag from being automatically set when the message data is retrieved.

Return Value

If the function succeeds, the return value is zero. If the function fails, the return value is IMAP_ERROR. To get extended error information, call ImapGetLastError.

Remarks

The ImapGetMessage function is used to retrieve a message from the server and copy it into a local buffer. The function may be used in one of two ways, depending on the needs of the application. The first method is to pre-allocate a buffer large enough to store the contents of the message. In this case, the lpvMessage parameter will point to the buffer that was allocated, the value that the lpdwLength parameter points to should be initialized to the size of that buffer.

The second method that can be used is have the lpvMessage parameter point to a global memory handle which will contain the message data when the function returns. In this case, the value that the lpdwLength parameter points to must be initialized to zero. It is important to note that the memory handle returned by the function must be freed by the application, otherwise a memory leak will occur.

This function will cause the current thread to block until the transfer completes, a timeout occurs or the transfer is canceled. During the transfer, the IMAP_EVENT_PROGRESS event will be periodically fired, enabling the application to update any user interface controls. Event notification must be enabled, either by calling ImapEnableEvents, or by registering a callback function using the ImapRegisterEvent function.

To determine if a message is a multipart MIME message, use the ImapGetMessageParts function. The return value specifies the number of parts in the message, with a value greater than one indicating that it is a multipart message. Combining the IMAP_SECTION_HEADER and IMAP_SECTION_BODY options will only return the header and body for the specified message if the nMessagePart parameter is zero. Due to a limitation of the IMAP FETCH command, if a message part is specified then only the body of that message part will be returned.

Note that unlike the SocketTools MIME API which considers the first message part to be zero, the IMAP protocol defines the first message part to be one.

Requirements

Client: Requires Windows 7, Windows Vista or Windows XP.
Server: Requires Windows Server 2008 or Windows Server 2003.
Header: Include cstools7.h.
Library: Use csmapav7.lib.

See Also

ImapGetMessageCount, ImapGetMessageHeaders, ImapGetMessageParts, ImapStoreMessage

Copyright © 2012 Catalyst Development Corporation. All rights reserved.