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 (hObject、KernelMode) 相同。 如需關閉核心句柄的詳細資訊,請參閱 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 |