WINHTTP_STATUS_CALLBACK回调函数 (winhttp.h)

项目
03/04/2024

WINHTTP_STATUS_CALLBACK类型表示应用程序定义的状态回调函数。

语法

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

参数

[in] hInternet

调用回调函数的句柄。

[in] dwContext

指向 DWORD 的指针，该指针指定与 hInternet 参数中的句柄关联的应用程序定义的上下文值。

可以通过使用 WINHTTP_OPTION_CONTEXT_VALUE 选项调用 WinHttpSetOption，将上下文值分配给会话、连接或请求句柄。或者， WinHttpSendRequest 可用于将上下文值与请求句柄相关联。

[in] dwInternetStatus

指向一个 DWORD，该 DWORD 指定指示调用回调函数的原因的状态代码。这可以是以下值之一：

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

关闭与服务器的连接。 lpvStatusInformation 参数为 NULL。

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

已成功连接到服务器。 lpvStatusInformation 参数包含指向 LPWSTR 的指针，该指针以点表示法指示服务器的 IP 地址。

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

连接到服务器。 lpvStatusInformation 参数包含指向 LPWSTR 的指针，该指针以点表示法指示服务器的 IP 地址。

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

已成功关闭与服务器的连接。 lpvStatusInformation 参数为 NULL。

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

可以使用 WinHttpReadData 检索数据。 lpvStatusInformation 参数指向包含可用数据字节数的 DWORD。 dwStatusInformationLength 参数本身是 4 (DWORD) 的大小。

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

已创建 HINTERNET 句柄。 lpvStatusInformation 参数包含指向 HINTERNET 句柄的指针。

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

此句柄值已终止。 lpvStatusInformation 参数包含指向 HINTERNET 句柄的指针。此句柄不再有回调。

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

响应标头已收到，可用于 WinHttpQueryHeaders。 lpvStatusInformation 参数为 NULL。

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

从服务器收到中间 (100 级别) 状态代码消息。 lpvStatusInformation 参数包含指向指示状态代码的 DWORD 的指针。

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

已成功找到服务器的 IP 地址。 lpvStatusInformation 参数包含指向 LPWSTR 的指针，该指针指示已解析的名称。

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

已成功从服务器读取数据。 lpvStatusInformation 参数包含指向调用 WinHttpReadData 中指定的缓冲区的指针。 dwStatusInformationLength 参数包含读取的字节数。

WinHttpWebSocketReceive 使用时，lpvStatusInformation 参数包含指向WINHTTP_WEB_SOCKET_STATUS结构的指针，dwStatusInformationLength 参数指示 lpvStatusInformation 的大小。

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

等待服务器响应请求。 lpvStatusInformation 参数为 NULL。

WINHTTP_CALLBACK_STATUS_REDIRECT

HTTP 请求将自动重定向请求。 lpvStatusInformation 参数包含指向指示新 URL 的 LPWSTR 的指针。此时，应用程序可以使用重定向响应读取服务器返回的任何数据，并且可以查询响应标头。它还可以通过关闭句柄来取消操作。

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

发送 HTTP 请求时出错。 lpvStatusInformation 参数包含指向WINHTTP_ASYNC_RESULT结构的指针。其 dwResult 成员指示被调用函数的 ID，dwError 指示返回值。

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

已成功将信息请求发送到服务器。 lpvStatusInformation 参数包含指向 DWORD 的指针，该指针指示发送的字节数。

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

查找服务器名称的 IP 地址。 lpvStatusInformation 参数包含指向要解析的服务器名称的指针。

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

已成功从服务器收到响应。 lpvStatusInformation 参数包含指向指示接收字节数的 DWORD 的指针。

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

在与服务器建立安全 (HTTPS) 连接时遇到一个或多个错误。 lpvStatusInformation 参数包含指向 DWORD 的指针，该指针是错误值的按位 OR 组合。有关详细信息，请参阅 lpvStatusInformation 的说明。

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

将信息请求发送到服务器。 lpvStatusInformation 参数为 NULL。

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

请求已成功完成。 lpvStatusInformation 参数是传递给 WinHttpSendRequest (初始请求正文) 的 lpOptional 值，dwStatusInformationLength 参数指示 (传递到 WinHttpSendRequest) 传递到 winHttpSendRequest 的 dwOptionalLength 值成功写入此类初始正文字节的数目。

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

数据已成功写入服务器。 lpvStatusInformation 参数包含指向 DWORD 的指针，该指针指示写入的字节数。

当 WinHttpWebSocketSend 使用时，lpvStatusInformation 参数包含指向WINHTTP_WEB_SOCKET_STATUS结构的指针，dwStatusInformationLength 参数指示 lpvStatusInformation 的大小。

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

通过调用 WinHttpGetProxyForUrlEx 启动的操作已完成。可以使用 WinHttpReadData 检索数据。

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

通过调用 WinHttpWebSocketClose 成功关闭了连接。 lpvStatusInformation 参数为 NULL。

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

通过调用 WinHttpWebSocketShutdown 成功关闭连接。 lpvStatusInformation 参数为 NULL。

[in] lpvStatusInformation

指向缓冲区的指针，该缓冲区指定与回调函数的此调用相关的信息。这些数据的格式取决于 dwInternetStatus 参数的值。有关详细信息，请参阅 dwInternetStatus。

如果 dwInternetStatus 参数WINHTTP_CALLBACK_STATUS_SECURE_FAILURE，则 lpvStatusInformation 指向 DWORD，该 DWORD 是以下一个或多个值的按位 OR 组合。

值	含义
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED	证书吊销检查已启用，但吊销检查未能验证证书是否已吊销。用于检查吊销的服务器可能无法访问。
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT	SSL 证书无效。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED	SSL 证书已吊销。
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA	函数不熟悉生成服务器证书的证书颁发机构。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID	SSL 证书公用名 (主机名字段) 不正确，例如，如果输入 www.microsoft.com 且证书上的公用名显示 www.msn.com。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID	从服务器收到的 SSL 证书日期不正确。证书已过期。
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR	应用程序在加载 SSL 库时遇到内部错误。

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT状态回调提供一个 dwStatusInformationLength 值，该值对应于 lpvStatusInformation 所指向的 LPWSTR 的字符计数。

返回值

无

备注

回调函数必须是线程安全且可重入的，因为它可以在另一个线程上为单独的请求调用，并在当前请求的同一线程上重新进入。因此，必须对其进行编码，以在处理时安全地处理重新进入。当 dwInternetStatus 参数等于 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING 时，回调不需要能够处理同一请求的重入，因为此回调保证是最后一次，并且不会在处理此请求的其他消息时发生。

状态回调函数通过通知标志接收有关异步操作状态的更新。指示特定操作已完成的通知称为完成通知，或只是完成通知。下表列出了收到此标志时完成的六个完成标志和相应的函数。

完成标志	函数
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE	WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE	WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE	WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE	WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE	WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR	发生错误时，上述任一项函数均会执行。

由于回调是在处理请求期间进行的，因此应用程序应在回调函数中花费尽可能多的时间，以避免降低网络上的数据吞吐量。例如，在回调函数中显示对话框可能是一个冗长的操作，服务器会终止请求。

可以在与启动请求的线程不同的线程上下文中调用回调函数。

同样，异步调用 WinHttp 时没有回调线程相关性：调用可能从一个线程开始，但其他任何线程都可以接收回调。

注意有关 Windows XP 和 Windows 2000 中的实现的详细信息，请参阅运行时要求。

要求

要求	值
最低受支持的客户端	Windows XP、Windows 2000 Professional 和 SP3 [仅限桌面应用]
最低受支持的服务器	Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用]
目标平台	Windows
标头	winhttp.h
可再发行组件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。

另请参阅

WinHTTP 版本

WinHttpSetStatusCallback

通过