WinHTTP 中的 HINTERNET 句柄
Microsoft Windows HTTP 服务(WinHTTP)使用句柄跟踪使用 HTTP 协议时所需的设置和信息。 每个句柄维护与 HTTP 会话、与 HTTP 服务器的连接或特定资源相关的信息。 本主题介绍各种类型的句柄、这些句柄的命名约定及其分层结构。
关于 HINTERNET 句柄
WinHTTP 创建的和使用句柄称为 HINTERNET 句柄。 WinHTTP 函数返回 HINTERNET 句柄,这些句柄不能与其他句柄互换,因此它们不能与 ReadFile 或 CloseHandle等函数一起使用。 同样,其他句柄不能与 WinHTTP 函数一起使用。 例如,无法将 CreateFile 返回的句柄传递给 winHttpReadData。 当使用句柄的 API 调用正在进行时,这些 HINTERNET 句柄无法关闭。 为了避免争用条件,只要 API 调用正在进行,应用程序应保护句柄并防止其关闭。
Microsoft Win32 Internet (WinInet) 函数还使用 HINTERNET 句柄。 但是,WinInet 函数中使用的句柄不能与 WinHTTP 函数中使用的句柄交换。 有关 WinInet 的详细信息,请参阅 关于 WinINet。
WinHttpCloseHandle 函数关闭 WinHTTP HINTERNET 句柄。
命名句柄
在整个 WinHTTP 文档中,应用程序编程接口(API)中的函数说明和示例代码显示了创建和使用各种类型的 HINTERNET 句柄。 为了跟踪可用的不同类型的句柄,这些句柄的命名是一致的。 下表显示了文档中约定使用的标识符。
句柄类型 | 函数创建句柄 | 标识符 |
---|---|---|
泛型句柄 | WinHttpOpen、WinHttpConnect或 WinHttpOpenRequest | hInternet |
会话句柄 | WinHttpOpen | hSession |
连接句柄 | WinHttpConnect | hConnect |
请求句柄 | WinHttpOpenRequest | hRequest |
Web 套接字句柄 | WinHttpWebSocketCompleteUpgrade | hWebSocket |
句柄层次结构
HINTERNET 句柄保留在层次结构中。 WinHttpOpen 返回的句柄是 HINTERNET 句柄的会话。 调用 WinHttpOpen 初始化 WinHTTP 函数,并开始一个会话上下文,该上下文在会话句柄的整个生命周期内维护用户信息和设置。 WinHttpConnect 指定目标 HTTP 或 HTTPS 服务器,并创建 HINTERNET 句柄的连接。 默认情况下,连接句柄继承会话句柄的设置。 WinHttpOpenRequest 调用指定的每个资源都会分配一个请求 HINTERNET 句柄。
下图说明了 HINTERNET 句柄 层次结构。 关系图中的每个框都表示一个 WinHTTP 函数,该函数返回 HINTERNET 句柄。
创建句柄的
关闭句柄后,应用程序必须准备好接收句柄上的回调通知,直到返回最终 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED 值,以指示句柄已完全关闭(或直到应用程序执行其自己的等效同步,例如跟踪和等待挂起异步作的任何回调,并确保不使用该句柄再尝试任何作)。
会话句柄称为用于创建的任何连接句柄的父级;同样,连接句柄及其父会话句柄都称为连接句柄用于创建的任何请求句柄的父级。
当父句柄关闭时,即使它本身未关闭,其任何子句柄也会间接失效,后续使用它们的请求会失败,并 ERROR_INVALID_HANDLE错误。 无法依赖挂起的异步请求来正确完成。
下图显示了使用 WinHttpOpenRequest创建的 HINTERNET 句柄的函数。 阴影框表示创建句柄的 WinHTTP 函数,纯框显示使用这些 HINTERNET 句柄的函数。 此关系图还进行组织,以显示正常调用 WinHTTP 函数的顺序。
创建句柄的
句柄层次结构的说明
首先,使用 WinHttpOpen创建会话句柄。 WinHttpConnect 需要会话句柄作为其第一个参数,并返回指定服务器的连接句柄。 请求句柄由 WinHttpOpenRequest创建,该句柄使用由 WinHttpConnect创建的连接句柄。 如果应用程序选择向请求添加其他标头,或者应用程序需要设置身份验证凭据 ,则可以使用此请求句柄调用 winHttpSetCredentials 和 WinHttpSetCredentials。 请求由 WinHttpSendRequest发送,后者使用请求句柄。 发送请求后,可以使用 WinHttpWriteData将其他数据发送到服务器,或者应用程序可以直接跳到 WinHttpReceiveResponse,以指定不会向服务器发送更多信息。 此时,根据应用程序的用途,请求句柄可用于调用 WinHttpQueryHeaders、WinHttpQueryAuthSchemes,或者检索具有 WinHttpQueryDataAvailable 和 WinHttpReadData的资源。
句柄层次结构中的 Web 套接字
Web 套接字句柄继承自连接和会话句柄,并在句柄层次结构中占据与请求句柄类似的位置。 若要创建 Web 套接字句柄,请求句柄必须存在;但是,创建 Web 套接字句柄后,请求可能会关闭,并且 Web 套接字句柄将继续正常运行。