INT GetMessageHeaders(
	LONG nMessageId,
	LPBYTE lpHeaders,
	LPDWORD lpdwLength
);

INT GetMessageHeaders(
	LONG nMessageId,
	HGLOBAL* lpHeaders,
	LPDWORD lpdwLength
);

INT GetMessageHeaders(
	LONG nMessageId,
	CString& strHeaders
);

The GetMessageHeaders method retrieves the headers for the specified message from the server.

Parameters

nMessageId

Number of message to retrieve from the server. This value must be greater than zero.

lpHeaders

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

lpdwLength

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

Return Value

If the method succeeds, the return value is zero. If the method fails, the return value is POP_ERROR. To get extended error information, call GetLastError.

Remarks

The GetMessageHeaders method is used to retrieve an message header block from the server and copy it into a local buffer. The method 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 file. In this case, the lpHeaders 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 lpHeaders parameter point to a global memory handle which will contain the message headers when the method 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 method must be freed by the application, otherwise a memory leak will occur.

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

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: cspopv10.lib

See Also

GetHeaderValue, GetMessage, GetMessageId, OpenMessage

Copyright © 2023 Catalyst Development Corporation. All rights reserved.