共用方式為


obCloseHandle 函式 (wdm.h)

ObCloseHandle 例程會關閉物件句柄。

語法

NTSTATUS ObCloseHandle(
  [in] HANDLE          Handle,
  [in] KPROCESSOR_MODE PreviousMode
);

參數

[in] Handle

任何型別之系統提供物件的句柄。

[in] PreviousMode

指定開啟句柄之線程的先前處理器模式。 若要關閉核心句柄,請將此參數設定為 KernelMode。 若要關閉 使用者句柄,請將此參數設定為 UserMode。 如需這兩個句柄類型的詳細資訊,請參閱。

傳回值

如果呼叫成功,ObCloseHandle 會傳回STATUS_SUCCESS。 可能的錯誤傳回值包括下列NTSTATUS代碼。

傳回碼 Description
STATUS_INVALID_HANDLE 句柄 不是有效的句柄。
STATUS_HANDLE_NOT_CLOSABLE 呼叫線程沒有關閉句柄的許可權。

備註

內核模式驅動程式會呼叫 ObCloseHandle ,以關閉 Windows 核心所建立之任何類型的物件的句柄。 驅動程式必須在不再需要句柄時立即關閉其開啟的每個句柄。

在 ObCloseHandle 關閉物件的句柄之後,呼叫端必須將句柄視為無效,並避免使用句柄來存取物件。 不過,其他句柄可能會在相同的物件上保持開啟狀態。 在 ObCloseHandle 呼叫期間,系統會遞減物件的句柄計數,並檢查是否可以刪除物件。 系統不會刪除物件,直到關閉所有物件的句柄,以及釋放物件的所有參考計數指標為止。

PreviousMode 參數會指定要關閉的句柄是核心句柄還是使用者句柄。 若要關閉核心句柄,請將 PreviousMode 設定為 KernelMode。 若要關閉使用者句柄,請將 PreviousMode 設定為 UserMode

核心句柄是由系統線程開啟的句柄,或是由指派OBJ_KERNEL_HANDLE屬性給句柄的核心模式驅動程式所開啟。 (例如,OBJ_KERNEL_HANDLE 請參閱 ZwCreateFile.) 如果內核模式驅動程序開啟句柄供其私用使用,而且此驅動程式會在使用者模式線程的內容中執行,驅動程式必須使用 OBJ_KERNEL_HANDLE 屬性開啟句柄。 此屬性可確保使用者模式應用程式無法存取句柄。

使用者句柄是由使用者模式應用程式開啟的句柄,或是由在使用者模式線程內容中執行但未使用 OBJ_KERNEL_HANDLE 屬性開啟句柄的核心模式驅動程式所開啟的句柄。 如果驅動程式建立使用者模式應用程式要使用的使用者句柄,但發生錯誤需要驅動程式代表應用程式關閉句柄,驅動程式可以呼叫 ObCloseHandle 來關閉句柄。

ZwClose 例程類似於 ObCloseHandle,但只能關閉核心句柄。 呼叫 ZwClose (hObject) 關閉核心句柄 hObject,與呼叫 ObCloseHandle (hObjectKernelMode) 相同。 如需關閉核心句柄的詳細資訊,請參閱 ZwClose

若要判斷句柄是核心句柄還是使用者句柄,接收句柄的驅動程式可以呼叫 ExGetPreviousMode 例程。 或者,驅動程式可以從描述 I/O 要求的 IRP 結構讀取 RequestorMode 字段。 I/O 管理員會將 RequestorMode 欄位設定為要求 I/O 作業之線程先前的處理器模式。

ObCloseHandle 的呼叫端不應該假設此例程會在傳回之前自動等候所有擱置的 I/O 作業完成。

如需詳細資訊,請參閱 物件句柄

ObCloseHandle 不會在 Windows 7 之前的頭檔中宣告。 若要在驅動程式中使用這個例程,請在驅動程式程式代碼中包含下列函式宣告:

#if (NTDDI_VERSION < NTDDI_WIN7)
NTKERNELAPI
NTSTATUS
  ObCloseHandle(
    __in HANDLE Handle,
    __in KPROCESSOR_MODE PreviousMode
    );
#endif

規格需求

需求
目標平台 Universal
標頭 wdm.h
程式庫 Ntoskrnl.lib
Dll Ntoskrnl.exe
IRQL PASSIVE_LEVEL

另請參閱

ExGetPreviousMode

IRP

ZwClose

ZwCreateFile