The GetData method is used to retrieve a resource 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 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 resource or 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 issuing the GET request to the server, 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.
When encountering a server error during a request, the
GetData method normally returns HTTP_ERROR, and no data is
copied into the caller-provided buffer. The last error code for the
current thread is updated to reflect the general cause of the failure,
allowing the application to handle this error condition appropriately.
Additionally, servers may provide further details about the failure,
such as XML or JSON formatted data containing specific error codes or
diagnostic messages.
To capture this error information, you can utilize the
HTTP_TRANSFER_ERRORDATA option. When this option is enabled, the
behavior of GetData changes; it does not return HTTP_ERROR
for server error statuses. Instead, any error data provided in the
server's response, regardless of its format, is copied into the buffer
provided by the caller.
If compression has been enabled and the server returns compressed
data, it will be automatically expanded before being returned to the
caller. This will result in a difference between the value returned in
the lpdwLength parameter, which contains the actual number of
bytes copied into the buffer, and the values reported by
GetTransferStatus. For example, if the server returns 5,000
bytes of compressed data that expands into 15,000 bytes, this function
will return 15,000 as the number of bytes copied into the buffer.
However, the GetTransferStatus method will return the
content length as the original 5,000 bytes of compressed data. For
this reason, you should always use the value returned in the
lpdwLength parameter to determine the amount of data that
has been copied into the buffer.
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 HTTP_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.