WinHttpQueryDataAvailable function (winhttp.h)
The WinHttpQueryDataAvailable function returns the amount of data, in bytes, available to be read with WinHttpReadData.
Syntax
WINHTTPAPI BOOL WinHttpQueryDataAvailable(
[in] HINTERNET hRequest,
[out] LPDWORD lpdwNumberOfBytesAvailable
);
Parameters
[in] hRequest
A valid HINTERNET handle returned by WinHttpOpenRequest. WinHttpReceiveResponse must have been called for this handle and have completed before WinHttpQueryDataAvailable is called.
[out] lpdwNumberOfBytesAvailable
A pointer to an unsigned long integer variable that receives the number of available bytes. When WinHTTP is used in asynchronous mode, always set this parameter to NULL and retrieve data in the callback function; not doing so can cause a memory fault.
Return value
Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error data, call GetLastError. Among the error codes returned are the following.
| Error Code | Description |
|---|---|
|
The connection with the server has been reset or terminated, or an incompatible SSL protocol was encountered. For example, WinHTTP version 5.1 does not support SSL2 unless the client specifically enables it. |
|
The requested operation cannot complete because the handle supplied is not in the correct state. |
|
The type of handle supplied is incorrect for this operation. |
|
An internal error has occurred. |
|
The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed. |
|
The request has timed out. |
|
Not enough memory was available to complete the requested operation. (Windows error code) |
Remarks
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 it returns FALSE, it failed and you can call GetLastError to get extended error information. If it returns TRUE, use the WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE 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.
The amount of data that remains is not recalculated until all available data indicated by the call to WinHttpQueryDataAvailable is read.
Use the return value of WinHttpReadData to determine when a response has been completely read.
If a status callback function has been installed with WinHttpSetStatusCallback, then those of the following notifications that have been set in the dwNotificationFlags parameter of WinHttpSetStatusCallback indicate progress in checking for available data:
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE
Examples
The following example shows how to use secure transaction semantics to download a resource from an HTTPS server. The sample code initializes the WinHTTP API, selects a target HTTPS server, and 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.
Important
If you want some data as quickly as possible (that is, you're processing and parsing data as you receive it), then you should call WinHttpQueryDataAvailable and WinHttpReadData. If you're trying to download the entire response as quickly as possible, then call WinHttpReadData directly, because WinHttpReadData tries to fill your buffer before completing.
Also, the code example below allocates on every loop iteration. For production code, where performance is important, you could instead start with an appropriately-sized buffer (perhaps 1 megabyte), and resize that if necessary. In practice, WinHttpQueryDataAvailable returns no more than 8 kilobytes.
DWORD dwSize = 0;
DWORD dwDownloaded = 0;
LPSTR pszOutBuffer;
BOOL bResults = FALSE;
HINTERNET hSession = NULL,
hConnect = NULL,
hRequest = NULL;
// Use WinHttpOpen to obtain a session handle.
hSession = WinHttpOpen( L"WinHTTP Example/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
// Specify an HTTP server.
if (hSession)
hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
INTERNET_DEFAULT_HTTPS_PORT, 0);
// Create an HTTP request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
NULL, WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
WINHTTP_FLAG_SECURE);
// Send a request.
if (hRequest)
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0, WINHTTP_NO_REQUEST_DATA, 0,
0, 0);
// End the request.
if (bResults)
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Continue to verify data until there is nothing left.
if (bResults)
do
{
// Verify available data.
dwSize = 0;
if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
printf( "Error %u in WinHttpQueryDataAvailable.\n",
GetLastError());
// Allocate space for the buffer.
pszOutBuffer = new char[dwSize+1];
if (!pszOutBuffer)
{
printf("Out of memory\n");
dwSize=0;
}
else
{
// Read the Data.
ZeroMemory(pszOutBuffer, dwSize+1);
if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer,
dwSize, &dwDownloaded))
printf( "Error %u in WinHttpReadData.\n", GetLastError());
else
printf( "%s\n", pszOutBuffer);
// Free the memory allocated to the buffer.
delete [] pszOutBuffer;
}
} while (dwSize > 0);
// Report any errors.
if (!bResults)
printf( "Error %d has occurred.\n", GetLastError());
// Close open handles.
if (hRequest) WinHttpCloseHandle(hRequest);
if (hConnect) WinHttpCloseHandle(hConnect);
if (hSession) WinHttpCloseHandle(hSession);
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP, Windows 2000 Professional with SP3 [desktop apps only] |
| Minimum supported server | Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only] |
| Target Platform | Windows |
| Header | winhttp.h |
| Library | Winhttp.lib |
| DLL | Winhttp.dll |
| Redistributable | WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000. |