CloseHandle 函式 (handleapi.h)

發行項
02/29/2024

關閉開啟的物件句柄。

語法

BOOL CloseHandle(
  [in] HANDLE hObject
);

參數

[in] hObject

開啟物件的有效句柄。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果應用程式是在調試程式下執行，則函式會在收到無效的句柄值或虛擬句柄值時擲回例外狀況。如果您關閉句柄兩次，或在 FindFirstFile 函式傳回的句柄上呼叫 CloseHandle，而不是呼叫 FindClose 函式，就會發生這種情況。

備註

CloseHandle 函式會將句柄關閉為下列物件：

存取權杖
通訊裝置
主控台輸入
控制台畫面緩衝區
事件
檔案
檔案對應
I/O 完成埠
作業
Mailslot
記憶體資源通知
Mutex
具名管道
Pipe
流程
Semaphore
執行緒
交易
可等候的定時器

建立這些物件的函式檔指出當您完成物件時，應該使用 CloseHandle ，以及在關閉句柄之後，物件上的擱置作業會發生什麼情況。一般而言， CloseHandle 會使指定的物件句柄失效、遞減物件的句柄計數，並執行物件保留檢查。關閉對象的最後一個句柄之後，物件就會從系統中移除。如需這些物件的建立者函式摘要，請參閱核心物件。

一般而言，應用程式應該針對開啟的每個句柄呼叫 CloseHandle 一次。如果使用句柄的函式因ERROR_INVALID_HANDLE而失敗，通常不需要呼叫 CloseHandle ，因為此錯誤通常表示句柄已失效。不過，某些函式會使用ERROR_INVALID_HANDLE來表示物件本身不再有效。例如，嘗試使用網路上檔案句柄的函式，如果網路連線已中斷，ERROR_INVALID_HANDLE可能會失敗，因為檔案物件已無法使用。在此情況下，應用程式應該關閉句柄。

如果交易句柄，則所有系結至交易的句柄都應該在認可交易之前關閉。如果使用 FILE_FLAG_DELETE_ON_CLOSE 旗標呼叫 CreateFileTransacted 來開啟交易句柄，則在應用程式關閉句柄並呼叫 CommitTransaction 之前，不會刪除檔案。如需交易對象的詳細資訊，請參閱使用交易。

關閉線程句柄不會終止相關聯的線程或移除線程物件。關閉進程句柄不會終止相關聯的進程或移除進程物件。若要移除線程物件，您必須終止線程，然後關閉線程的所有句柄。如需詳細資訊，請參閱終止線程。若要移除進程物件，您必須終止進程，然後關閉進程的所有句柄。如需詳細資訊，請參閱終止進程。

即使檔案檢視仍在開啟，關閉檔案對應的句柄仍可成功。如需詳細資訊，請參閱關閉檔案對應物件。

請勿使用 CloseHandle 函式 來關閉套接字。請改用 closesocket 函式，釋放與套接字相關聯的所有資源，包括套接字物件的句柄。如需詳細資訊，請參閱套接字關閉。

請勿使用 CloseHandle 函式 關閉開啟登錄機碼的句柄。請改用 RegCloseKey 函式。 CloseHandle 不會關閉登錄機碼的句柄，但不會傳回錯誤來指出此失敗。

範例

dwPriorityClass = 0;
hProcess = OpenProcess( PROCESS_ALL_ACCESS, FALSE, pe32.th32ProcessID );
if( hProcess == NULL )
	printError( TEXT("OpenProcess") );
else
{
	dwPriorityClass = GetPriorityClass( hProcess );
	if( !dwPriorityClass )
	printError( TEXT("GetPriorityClass") );
	CloseHandle( hProcess );
}

若要查看內容中的這個範例，請參閱建立快照集和檢視進程。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	handleapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll