The GetData method is used to download the contents of a
remote file 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 lpBuffer 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 lpBuffer
parameter point to a global memory handle which will contain the file
data 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.
See the example code below.
If the third method or fourth method is used, where the data is
returned in a string buffer, the data may be modified
so that the end-of-line character sequence matches the convention
used by the Windows platform (a carriage return character followed by
a linefeed). If Unicode is being used, the data will be converted
from a byte array to a Unicode string. An application should only use
these versions of the GetData method if the remote file
contains text.
It is important for your application to initialize the value of the
lpdwLength parameter correctly. This parameter must be passed
by reference and if it is not initialized properly it can cause
unexpected behavior or corrupt the process heap. If an error occurs
when downloading the file, the variable passed to this method may
have a value of zero when the method returns, indicating no data
has been returned to the caller.
This method will cause the current thread to block until the file
transfer completes, a timeout occurs or the transfer is canceled.
During the transfer, the FTP_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.
To determine the current status of a file transfer while it is in
progress, use the GetTransferStatus method.
HGLOBAL hgblBuffer = (HGLOBAL)NULL;
LPBYTE lpBuffer = (LPBYTE)NULL;
DWORD cbBuffer = 0;
// Return the file data into block of global memory allocated by
// the GlobalAlloc function; the handle to this memory will be
// returned in the hgblBuffer parameter
nResult = pClient->GetData(lpszRemoteFile, &hgblBuffer, &cbBuffer);
if (nResult != FTP_ERROR)
{
// Lock the global memory handle, returning a pointer to the
// contents of the file data
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);
}