WinHttpCloseHandle 函数 (winhttp.h)

  • 项目

WinHttpCloseHandle 函数关闭单个 HINTERNET 句柄 (请参阅 WinHTTP) 中的 HINTERNET 句柄。

语法

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

参数

[in] hInternet

有效的 HINTERNET 句柄 (请参阅 WinHTTP 中的 HINTERNET 句柄) 要关闭。

返回值

如果成功关闭句柄，则为 TRUE，否则为 FALSE。 要获得更多的错误信息，请调用 GetLastError。 返回的错误代码如下。

错误代码 说明
ERROR_WINHTTP_SHUTDOWN
 WinHTTP 函数支持正在关闭或卸载。
ERROR_WINHTTP_INTERNAL_ERROR
 发生了内部错误。
ERROR_NOT_ENOUGH_MEMORY
 内存不足，无法完成请求的操作。 (Windows 错误代码)

注解

即使在异步模式下使用 WinHTTP， (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时，此函数也会同步运行。 返回值指示成功或失败。 要获得更多的错误信息，请调用 GetLastError。

如果为正在关闭的句柄注册了状态回调，并且该句柄是使用非 NULL 上下文值创建的，则会进行 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING 回调。 这是从句柄进行的最后一个回调，指示正在销毁句柄。

应用程序可以通过使用 WinHttpCloseHandle 关闭 HINTERNET 请求句柄来终止正在进行的异步请求。 请牢记以下几点：

  • 应用程序在 WinHTTP 句柄上调用 WinHttpCloseHandle 后，无法从任何线程使用该句柄调用任何其他 WinHTTP API 函数。
  • 即使在调用 WinHttpCloseHandle 返回之后，应用程序也必须准备好接收关闭句柄的回调，因为 WinHTTP 可以异步拆解句柄。 如果异步请求无法成功完成，回调将收到WINHTTP_CALLBACK_STATUS_REQUEST_ERROR通知。
  • 如果应用程序将上下文数据结构或对象与句柄相关联，则应保留该绑定，直到回调函数收到 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING 通知。 这是 WinHTTP 在从内存中删除句柄对象之前发送的最后一个回调通知。 为了接收WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING回调通知，应用程序必须在 WinHttpSetStatusCallback 调用中启用 WINHTTP_CALLBACK_FLAG_HANDLES 标志。
  • 在调用 WinHttpCloseHandle 之前，应用程序可以调用 WinHttpSetStatusCallback 以指示不应再进行回调：

    WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );

    然后，上下文数据结构似乎可以立即释放，而不必等待 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING 通知，但情况并非如此：WinHTTP 不会将 WinHttpSetStatusCallback 与源自工作线程的回调同步。 因此，从另一个线程进行的回调可能已在进行，即使对回调函数指针执行 NULL 删除并删除句柄的上下文数据结构，应用程序也可以收到回调通知。 由于这种潜在的争用条件，在收到 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING 通知之前，在释放上下文结构时要保持保守。

应用程序绝不应对同步请求调用 WinHttpCloseHandle 。 这会创建争用条件。 有关详细信息 ，请参阅 WinHTTP 中的 HINTERNET 句柄 。
注意 对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的 运行时要求 部分。
 

要求

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

另请参阅

关于 Microsoft Windows HTTP Services (WinHTTP)

WinHTTP 版本

WinHttpConnect

WinHttpOpen

WinHttpOpenRequest