WinHttpReadData

The WinHttpReadData function reads data from a handle opened by the WinHttpOpenRequest function.

BOOL WinHttpReadData(

HINTERNET hRequest,

LPVOID lpBuffer,

DWORD dwNumberOfBytesToRead,

LPDWORD lpdwNumberOfBytesRead

);

FUNCTION WinHttpReadData ( _

BYVAL hRequest AS DWORD, _

BYVAL lpBuffer AS DWORD, _

BYVAL dwNumberOfBytesToRead AS DWORD, _

lpdwNumberOfBytesRead AS DWORD _

) AS LONG

[in] Valid HINTERNET handle returned from a previous call to WinHttpOpenRequest. WinHttpReceiveResponse or WinHttpQueryDataAvailable must have been called for this handle and must have completed before WinHttpReadData is called. Although calling WinHttpReadData immediately after completion of WinHttpReceiveResponse avoids the expense of a buffer copy, doing so requires that the application use a fixed-length buffer for reading.

[out] Pointer to a buffer that receives the data read. Make sure that this buffer remains valid until WinHttpReadData has completed.

[out] Pointer to an unsigned long integer variable that receives the number of bytes read. WinHttpReadData sets this value to zero before doing any work or error checking. When using WinHTTP asynchronously, always set this parameter to NULL and retrieve the information in the callback function; not doing so can cause a memory fault.

Returns a valid session handle if successful, or NULL otherwise. To retrieve extended error information, call GetLastError. Among the error codes returned are:

Error Codes	Description
ERROR_WINHTTP_CONNECTION_ERROR	The connection with the server has been reset or terminated, or an incompatible SSL protocol was encountered. For example, WinHTTP 5.1 does not support SSL2 unless the client specifically enables it.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	The requested operation cannot be carried out because the handle supplied is not in the correct state.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	The type of handle supplied is incorrect for this operation.
ERROR_WINHTTP_INTERNAL_ERROR	An internal error has occurred.
ERROR_WINHTTP_OPERATION_CANCELLED	The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed.
ERROR_WINHTTP_RESPONSE_DRAIN_OVERFLOW	Returned when an incoming response exceeds an internal WinHTTP size limit.
ERROR_WINHTTP_TIMEOUT	The request has timed out.
ERROR_NOT_ENOUGH_MEMORY	Not enough memory was available to complete the requested operation. (Windows error code)

Even when WinHTTP is used in asynchronous mode (that is, when WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function can operate either synchronously or asynchronously. If this function returns FALSE, this function failed and you can call GetLastError to get extended error information. If this function returns TRUE, use the WINHTTP_CALLBACK_STATUS_READ_COMPLETE completion to determine whether this function was successful and the value of the parameters. The WINHTTP_CALLBACK_STATUS_REQUEST_ERROR completion indicates that the operation completed asynchronously, but failed.

Warning When WinHTTP is used in asynchronous mode, always set the lpdwNumberOfBytesRead parameter to NULL and retrieve the bytes read in the callback function; otherwise, a memory fault can occur.

When the read buffer is very small, WinHttpReadData might complete synchronously. If the WINHTTP_CALLBACK_STATUS_READ_COMPLETE completion triggers another call to WinHttpReadData, the situation can result in a stack overflow. In general, it is best to use a read buffer that is comparable in size, or larger than the internal read buffer used by WinHTTP, which is 8 KB.

If you are using WinHttpReadData synchronously, and the return value is TRUE and the number of bytes read is zero, the transfer has been completed and there are no more bytes to read on the handle. This is analogous to reaching end-of-file in a local file. If you are using the function asynchronously, the WINHTTP_CALLBACK_STATUS_READ_COMPLETE callback is called with the dwStatusInformationLength parameter set to zero when the end of a response is found.

Use the return value of WinHttpReadData rather than that of WinHttpQueryDataAvailable to determine whether the end of the response has been reached, because an improperly terminated response can cause WinHttpQueryDataAvailable to continue to indicate that more data is available even when the response has been completely read.

The buffer pointed to by lpBuffer is not always filled by calls to the WinHttpReadData function; sufficient data might not have arrived from the server.

For HINTERNET handles created by the WinHttpOpenRequest function and sent by WinHttpSendRequest, a call to WinHttpReceiveResponse must be made on the handle before WinHttpReadData can be used.

Single byte characters retrieved with WinHttpReadData are not converted to multi-byte characters.

When the read buffer is very small, WinHttpReadData may complete synchronously, and if the WINHTTP_CALLBACK_STATUS_READ_COMPLETE completion then triggers another call to WinHttpReadData, a stack overflow can result. It is best to use a read buffer that is 8 Kilobytes or larger in size.

If sufficient data has not arrived from the server, WinHttpReadData does not entirely fill the buffer pointed to by lpBuffer. The buffer must be large enough at least to hold the HTTP headers on the first read, and when reading HTML encoded directory entries, it must be large enough to hold at least one complete entry.

If a status callback function has been installed by using WinHttpSetStatusCallback, then those of the following notifications that have been set in the dwNotificationFlags parameter of WinHttpSetStatusCallback indicate progress in checking for available data:

The following example shows how to use secure transaction semantics to download a resource from an Secure Hypertext Transfer Protocol (HTTPS) server. The sample code initializes the WinHTTP application programming interface (API), selects a target HTTPS server, then opens and sends a request for this secure resource. WinHttpQueryDataAvailable is used with the request handle to determine how much data is available for download, then WinHttpReadData is used to read that data. This process repeats until the entire document has been retrieved and displayed.