|
|
| INT
PopGetMessageHeaders(
|
|
|
HCLIENT
hClient, |
|
|
|
|
LONG
nMessageId, |
|
|
|
|
LPVOID
lpvHeaders, |
|
|
|
|
LPDWORD
lpdwLength |
|
|
| );
|
The PopGetMessageHeaders function retrieves the headers
for the specified 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.
- lpvHeaders
- A pointer to a byte buffer which will contain the data
transferred from the remote 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 lpvHeaders parameter. If the
lpvHeaders 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.
Return Value
If the function succeeds, the return value is zero. If the
function fails, the return value is POP_ERROR. To get extended
error information, call PopGetLastError.
Remarks
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.
Requirements
Client: Requires Windows Vista, Windows XP or Windows
2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or
Windows 2000 Server.
Header: Include cstools6.h.
Library: Use cspopav6.lib.
See Also
PopGetHeaderValue, PopGetMessage, PopGetMessageId, PopOpenMessage
|
|