描述
WinHttpReadData功能从WinHttpOpenRequest功能打开的句柄中读取数据。
C / C ++语法
BOOL WinHttpReadData( HINTERNET hRequest, LPVOID lpBuffer, DWORD dwNumberOfBytesToRead, LPDWORD lpdwNumberOfBytesRead ); |
PowerBASIC 语法
FUNCTION WinHttpReadData ( _ BYVAL hRequest AS DWORD, _ BYVAL lpBuffer AS DWORD, _ BYVAL dwNumberOfBytesToRead AS DWORD, _ lpdwNumberOfBytesRead AS DWORD _ ) AS LONG |
参数
hRequest
[in]有效的HINTERNET句柄从前一次调用返回WinHttpOpenRequest.必须已经为此句柄调用WinHttpReceiveResponse或WinHttpQueryDataAvailable，并且必须在调用WinHttpReadData之前完成。尽管在WinHttpReceiveResponse完成后立即致电WinHttpReadData，但是避免了缓冲区副本的费用，因此要求应用程序使用固定长度的缓冲区进行读取。
lpBuffer
[out]指向接收数据读取的缓冲区的指针。在WinHttpReadData完成之前，请确保该缓冲区保持有效。
dwNumberOfBytesRead
[in]包含要读取的字节数的无符号长整型值。
lpdwNumberOfBytesRead
[out]指向无符号长整数变量的指针，该变量接收读取的字节数。WinHttpReadData在进行任何工作或错误检查之前将此值设置为零。当异步使用WinHTTP时，始终将此参数设置为NULL并检索回调函数中的信息;不这样做可能会导致内存故障。
返回值
如果成功，返回一个有效的会话句柄，否则返回NULL。要检索扩展错误信息，请调用GetLastError.返回的错误代码有：
错误代码 |
描述 |
ERROR_WINHTTP_CONNECTION_ERROR |
与服务器的连接已重置或终止，或遇到不兼容的SSL协议。例如，WinHTTP 5.1不支持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错误代码） |
备注
即使在异步模式下使用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，并且读取的字节数为零，则传输已完成，并且句柄上不再有字节要读取。这类似于在本地文件中到达文件末尾。如果您异步使用该函数，则在发现响应结束时，将调用WINHTTP_CALLBACK_STATUS_READ_COMPLETE回调，并将dwStatusInformationLength参数设置为零。
使用WinHttpReadData的返回值而不是WinHttpQueryDataAvailable的返回值来确定是否已经达到响应的结束，因为不正确终止的响应可能导致WinHttpQueryDataAvailable继续指示更多数据可用，即使响应已经完全阅读
lpBuffer指向的缓冲区并不总是通过调用WinHttpReadData函数来填充;足够的数据可能没有从服务器到达。
对于由WinHttpOpenRequest函数创建并由WinHttpSendRequest发送的HINTERNET句柄，必须在WinHttpReadData之前对句柄进行调用WinHttpReceiveResponse.
使用WinHttpReadData检索的单字节字符不会转换为多字节字符。
当读缓冲区非常小时，WinHttpReadData可以同步完成，如果WINHTTP_CALLBACK_STATUS_READ_COMPLETE完成，则触发另一个调用WinHttpReadData，可能会导致堆栈溢出。最好使用大小为8千字节或更大的读取缓冲区。
如果没有从服务器得到足够的数据，WinHttpReadData不会完全填满lpBuffer指向的缓冲区。缓冲区必须足够大，至少要在第一次读取时保存HTTP头，当读取HTML编码的目录条目时，它必须足够大以容纳至少一个完整的条目。
如果使用WinHttpSetStatusCallback已经安装了状态回调函数，则在dwNotificationFlags参数WinHttpSetStatusCallback中设置的以下通知的那些指示在检查可用数据方面取得进展：
| · | WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE |
| · | WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED |
| · | WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED |
| · | WINHTTP_CALLBACK_STATUS_READ_COMPLETE |