CloseHandle 函式 (handleapi.h)
關閉開啟的物件句柄。
語法
BOOL CloseHandle(
[in] HANDLE hObject
);
參數
[in] hObject
開啟物件的有效句柄。
傳回值
如果函式成功，則傳回非零的值。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
如果應用程式是在調試程式下執行，則函式會在收到無效的句柄值或虛擬句柄值時擲回例外狀況。 如果您關閉句柄兩次，或在 FindFirstFile 函式傳回的句柄上呼叫 CloseHandle，而不是呼叫 FindClose 函式，就會發生這種情況。
備註
CloseHandle 函式會將句柄關閉為下列物件：
- 存取權杖
- 通訊裝置
- 主控台輸入
- 控制台畫面緩衝區
- 事件
- 檔案
- 檔案對應
- I/O 完成埠
- 作業
- Mailslot
- 記憶體資源通知
- Mutex
- 具名管道
- Pipe
- 流程
- Semaphore
- 執行緒
- 交易
- 可等候的定時器
一般而言，應用程式應該針對開啟的每個句柄呼叫 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 |