WINHTTP_STATUS_CALLBACK回调函数 (winhttp.h)

  • 项目

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 的指针，该 DWORD 指定与 hInternet 参数中的句柄关联的应用程序定义的上下文值。

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

[in] dwInternetStatus

指向指定状态代码的 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

从服务器检索安全套接字层 (SSL) 证书时遇到一个或多个错误。 lpvStatusInformation 参数包含标志。 有关详细信息，请参阅 lpvStatusInformation 的说明。

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

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

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

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

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