winHttpCloseHandle 函式 (winHTTP.h)

  • 發行項

WinHttpCloseHandle 函式會關閉單一 HINTERNET 句柄 (請參閱 WinHTTP) 中的 HINTERNET 句柄。

語法

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

參數

[in] hInternet

有效的 HINTERNET 句柄 (請參閱 WinHTTP) 中要關閉的 HINTERNET 句柄 。

傳回值

如果成功關閉句柄，則為TRUE，否則為 FALSE。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 傳回的錯誤碼如下。

錯誤碼 Description
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、具有 SP3 的 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 winhttp.h
程式庫 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