WinHttpReadData 函数 (winhttp.h)
WinHttpReadData 函数从 WinHttpOpenRequest 函数打开的句柄读取数据。
另请参阅 WinHttpReadDataEx。
语法
WINHTTPAPI BOOL WinHttpReadData(
[in] HINTERNET hRequest,
[out] LPVOID lpBuffer,
[in] DWORD dwNumberOfBytesToRead,
[out] LPDWORD lpdwNumberOfBytesRead
);
参数
[in] hRequest
从上一次调用 WinHttpOpenRequest 返回的有效 HINTERNET 句柄。 WinHttpReceiveResponse 或 WinHttpQueryDataAvailable 必须已为此句柄调用，并且必须在调用 WinHttpReadData 之前完成。 虽然在 WinHttpReceiveResponse 完成后立即调用 WinHttpReadData 可避免缓冲区复制费用，但这样做需要应用程序使用固定长度的缓冲区进行读取。
[out] lpBuffer
指向接收读取数据的缓冲区的指针。 确保此缓冲区在 WinHttpReadData 完成之前保持有效。
[in] dwNumberOfBytesToRead
包含要读取的字节数的无符号长整数值。
[out] lpdwNumberOfBytesRead
指向接收读取字节数的无符号长整数变量的指针。 WinHttpReadData 在执行任何工作或错误检查之前将此值设置为零。 异步使用 WinHTTP 时，始终将此参数设置为 NULL ，并在回调函数中检索信息;不这样做可能会导致内存故障。
返回值
如果成功，则返回 TRUE ，否则返回 FALSE 。 有关扩展的错误信息，请调用 GetLastError。 下表标识了返回的错误代码。
| 错误代码 | 说明 |
|---|---|
|
与服务器的连接已重置或终止，或者遇到不兼容的 SSL 协议。 例如，WinHTTP 5.1 不支持 SSL2，除非客户端专门启用 SSL2。 |
|
无法执行请求的操作，因为提供的句柄未处于正确的状态。 |
|
此操作提供的句柄类型不正确。 |
|
发生了内部错误。 |
|
操作被取消，通常是因为操作之前关闭了操作请求的句柄。 |
|
当传入响应超过内部 WinHTTP 大小限制时返回。 |
|
请求已超时。 |
|
内存不足，无法完成请求的操作。 (Windows 错误代码) |
注解
从 Windows Vista 和 Windows Server 2008 开始，WinHttp 使应用程序能够对发送到服务器的数据执行分块传输编码。 当 WinHttp 响应中存在 Transfer-Encoding 标头时， WinHttpReadData 会去除分块信息，然后再将数据提供给应用程序。
即使在异步模式下使用 WinHTTP， (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC，此函数也可以同步或异步运行。 如果此函数返回 FALSE，则此函数失败，你可以调用 GetLastError 来获取扩展的错误信息。 如果此函数返回 TRUE，请使用WINHTTP_CALLBACK_STATUS_READ_COMPLETE完成来确定此函数是否成功以及参数的值。 WINHTTP_CALLBACK_STATUS_REQUEST_ERROR完成指示操作异步完成，但失败。
如果同步使用 WinHttpReadData ，并且返回值为 TRUE 且读取的字节数为零，则表示传输已完成，并且句柄上不再有要读取的字节。 这类似于到达本地文件中的文件结尾。 如果异步使用 函数，则当找到响应的结尾时，将使用 dwStatusInformationLength 参数设置为零调用WINHTTP_CALLBACK_STATUS_READ_COMPLETE回调。
WinHttpReadData 尝试填充 lpBuffer 指向的缓冲区，直到响应中没有更多可用数据。 如果服务器未收到足够的数据，则不会填充缓冲区。
对于由 WinHttpOpenRequest 函数创建并由 WinHttpSendRequest 发送的 HINTERNET 句柄，必须在该句柄上调用 WinHttpReceiveResponse，然后才能使用 WinHttpReadData。
使用 WinHttpReadData 检索到的单字节字符不会转换为多字节字符。
当读取缓冲区非常小时， WinHttpReadData 可能会同步完成，如果 WINHTTP_CALLBACK_STATUS_READ_COMPLETE 完成，则触发对 WinHttpReadData 的另一次调用，可能会导致堆栈溢出。 最好使用大小为 8 KB 或更大的读取缓冲区。
如果服务器未收到足够的数据， WinHttpReadData 不会完全填满 lpBuffer 指向的缓冲区。 缓冲区必须足够大，至少足以在首次读取时保存 HTTP 标头;读取 HTML 编码的目录条目时，缓冲区必须足够大，以便保存至少一个完整条目。
如果使用 WinHttpSetStatusCallback 安装了状态回调函数，则在 WinHttpSetStatusCallback 的 dwNotificationFlags 参数中设置的以下通知指示检查可用数据的进度：
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
- WINHTTP_CALLBACK_STATUS_READ_COMPLETE
示例
以下示例演示如何使用安全事务语义从安全超文本传输协议 (HTTPS) 服务器下载资源。 示例代码 (API) 初始化 WinHTTP 应用程序编程接口，选择目标 HTTPS 服务器，然后打开并发送对此安全资源的请求。
WinHttpQueryDataAvailable 与请求句柄一起使用，以确定可供下载的数据量，然后使用 WinHttpReadData 读取该数据。 此过程将重复，直到检索并显示整个文档。
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);
// Keep checking for data until there is nothing left.
if (bResults)
{
do
{
// Check for available data.
dwSize = 0;
if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
{
printf( "Error %u in WinHttpQueryDataAvailable.\n",
GetLastError());
break;
}
// No more available data.
if (!dwSize)
break;
// Allocate space for the buffer.
pszOutBuffer = new char[dwSize+1];
if (!pszOutBuffer)
{
printf("Out of memory\n");
break;
}
// Read the Data.
ZeroMemory(pszOutBuffer, dwSize+1);
if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer,
dwSize, &dwDownloaded))
{
printf( "Error %u in WinHttpReadData.\n", GetLastError());
}
else
{
printf("%s", pszOutBuffer);
}
// Free the memory allocated to the buffer.
delete [] pszOutBuffer;
// This condition should never be reached since WinHttpQueryDataAvailable
// reported that there are bits to read.
if (!dwDownloaded)
break;
} while (dwSize > 0);
}
else
{
// Report any errors.
printf( "Error %d has occurred.\n", GetLastError() );
}
// Close any 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 或更高版本。 |