| |
| INT WINAPI PopGetMessage(
|
| |
HCLIENT hClient, |
|
| |
LONG nMessageId, |
|
| |
LPVOID lpvBuffer, |
|
| |
LPDWORD lpdwLength, |
|
| |
DWORD dwReserved |
|
| );
|
The PopGetMessage function retrieves the specified
message and copies the contents to a local buffer.
Parameters
- hClient
- Handle to the client session.
- nMessageId
- Number of message to retrieve from the server. This value must
be greater than zero.
- lpvBuffer
- 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 lpvBuffer parameter. If the
lpvBuffer 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
file that was downloaded.
- dwReserved
- A reserved parameter. This value should always be zero.
Return Value
If the function succeeds, the return value is the server result
code. If the function fails, the return value is POP_ERROR. To get
extended error information, call PopGetLastError.
Remarks
The PopGetMessage function is used to retrieve an 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
lpvBuffer 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 lpvBuffer
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. See the example code below.
This function will cause the current thread to block until the
complete message has been retrieved, a timeout occurs or the
operation 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.
To determine the current status of a transfer while it is in
progress, use the PopGetTransferStatus function.
Example
HGLOBAL hgblBuffer = (HGLOBAL)NULL;
LPBYTE lpBuffer = (LPBYTE)NULL;
DWORD cbBuffer = 0;
// Return the message into block of global memory allocated by
// the GlobalAlloc function; the handle to this memory will be
// returned in the hgblBuffer parameter
nResult = PopGetMessage(hClient,
nMessageId,
&hgblBuffer,
&cbBuffer,
0);
if (nResult != POP_ERROR)
{
// Lock the global memory handle, returning a pointer to the
// message text
lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
// After the data has been used, the handle must be unlocked
// and freed, otherwise a memory leak will occur
GlobalUnlock(hgblBuffer);
GlobalFree(hgblBuffer);
}
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 cspopav7.lib.
See Also
PopEnableEvents, PopGetMessageHeaders, PopGetTransferStatus, PopRegisterEvent
|
|