The PopGetMessageHeaders function is used to retrieve an
message header block 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 file. In this case, the
lpvHeaders 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 lpvHeaders
parameter point to a global memory handle which will contain the
message headers 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 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 PopEnableEvents, or by registering a callback function
using the PopRegisterEvent function.