WinHttpReadData 函数 (winhttp.h)

项目
08/27/2023

WinHttpReadData 函数从 WinHttpOpenRequest 函数打开的句柄读取数据。

语法

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。下表标识了返回的错误代码。

错误代码	说明
ERROR_WINHTTP_CONNECTION_ERROR	与服务器的连接已重置或终止，或者遇到不兼容的 SSL 协议。例如，WinHTTP 5.1 不支持 SSL2，除非客户端专门启用 SSL2。
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	无法执行请求的操作，因为提供的句柄未处于正确的状态。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	此操作提供的句柄类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR	发生了内部错误。
ERROR_WINHTTP_OPERATION_CANCELLED	操作被取消，通常是因为操作之前关闭了操作请求的句柄。
ERROR_WINHTTP_RESPONSE_DRAIN_OVERFLOW	当传入响应超过内部 WinHTTP 大小限制时返回。
ERROR_WINHTTP_TIMEOUT	请求已超时。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成请求的操作。 (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完成指示操作异步完成，但失败。

警告在异步模式下使用 WinHTTP 时，始终将 lpdwNumberOfBytesRead 参数设置为 NULL 并检索在回调函数中读取的字节;否则，可能会发生内存故障。

当读取缓冲区非常小时， WinHttpReadData 可能会同步完成。如果WINHTTP_CALLBACK_STATUS_READ_COMPLETE完成触发对 WinHttpReadData 的另一次调用，则这种情况可能会导致堆栈溢出。通常，最好使用大小相当或大于 WinHTTP 使用的内部读取缓冲区（8 KB）的读取缓冲区。

如果同步使用 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

注意对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的运行时要求部分。

示例

以下示例演示如何使用安全事务语义从安全超文本传输协议 (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 或更高版本。