WinHttpQueryDataAvailable 函数 (winhttp.h)
WinHttpQueryDataAvailable 函数返回可使用 WinHttpReadData 读取的数据量(以字节为单位)。
语法
WINHTTPAPI BOOL WinHttpQueryDataAvailable(
[in] HINTERNET hRequest,
[out] LPDWORD lpdwNumberOfBytesAvailable
);
参数
[in] hRequest
WinHttpOpenRequest 返回的有效 HINTERNET 句柄。 WinHttpReceiveResponse 必须已为此句柄调用,并在调用 WinHttpQueryDataAvailable 之前完成。
[out] lpdwNumberOfBytesAvailable
指向接收可用字节数的无符号长整数变量的指针。 在异步模式下使用 WinHTTP 时,始终将此参数设置为 NULL ,并在回调函数中检索数据;不这样做可能会导致内存故障。
返回值
如果函数成功,则返回 TRUE ,否则返回 FALSE 。 若要获取扩展的错误数据,请调用 GetLastError。 返回的错误代码如下。
错误代码 | 说明 |
---|---|
|
与服务器的连接已重置或终止,或者遇到不兼容的 SSL 协议。 例如,WinHTTP 版本 5.1 不支持 SSL2,除非客户端专门启用 SSL2。 |
|
请求的操作无法完成,因为提供的句柄未处于正确状态。 |
|
此操作提供的句柄类型不正确。 |
|
发生了内部错误。 |
|
操作被取消,通常是因为操作之前关闭了操作请求的句柄。 |
|
请求已超时。 |
|
内存不足,无法完成请求的操作。 (Windows 错误代码) |
注解
即使在异步模式下使用 WinHTTP, (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC,此函数也可以同步或异步运行。 如果返回 FALSE,则失败,你可以调用 GetLastError 以获取扩展的错误信息。 如果返回 TRUE,请使用WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE完成来确定此函数是否成功以及参数的值。 WINHTTP_CALLBACK_STATUS_REQUEST_ERROR完成指示操作异步完成,但失败。
在读取 对 WinHttpQueryDataAvailable 的调用指示的所有可用数据之前,不会重新计算剩余的数据量。
使用 WinHttpReadData 的返回值确定何时已完全读取响应。
如果状态回调函数已随 WinHttpSetStatusCallback 一起安装,则在 WinHttpSetStatusCallback 的 dwNotificationFlags 参数中设置的以下通知指示检查可用数据的进度:
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE
示例
以下示例演示如何使用安全事务语义从 HTTPS 服务器下载资源。 示例代码初始化 WinHTTP API,选择目标 HTTPS 服务器,然后打开并发送对此安全资源的请求。
WinHttpQueryDataAvailable 与请求句柄一起使用,以确定可供下载的数据量,然后使用 WinHttpReadData 读取该数据。 此过程将重复,直到检索并显示整个文档。
重要
如果希望尽快 (某些数据,即在收到数据) 处理和分析数据,则应调用 WinHttpQueryDataAvailable 和 WinHttpReadData。 如果尝试尽快下载整个响应,请直接调用 WinHttpReadData ,因为 WinHttpReadData 会在完成之前尝试填充缓冲区。
此外,下面的代码示例在每次循环迭代时分配。 对于性能非常重要的生产代码,可以改为从适当大小的缓冲区开始, (大约 1 兆字节) ,并在必要时调整大小。 实际上, WinHttpQueryDataAvailable 返回不超过 8 KB。
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);
要求
最低受支持的客户端 | Windows XP、Windows 2000 Professional SP3 [仅限桌面应用] |
最低受支持的服务器 | Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用] |
目标平台 | Windows |
标头 | winhttp.h |
Library | Winhttp.lib |
DLL | Winhttp.dll |
可再发行组件 | Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。 |