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 的指针,该指针指定与 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 参数指向包含可用数据字节数的 DWORDdwStatusInformationLength 参数本身是 4 (DWORD) 的大小。

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

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

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

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

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

响应标头已收到,可用于 WinHttpQueryHeaderslpvStatusInformation 参数为 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