ObCloseHandle 関数 (wdm.h)
ObCloseHandle ルーチンは、オブジェクト ハンドルを閉じます。
構文
NTSTATUS ObCloseHandle(
[in] HANDLE Handle,
[in] KPROCESSOR_MODE PreviousMode
);
パラメーター
[in] Handle
任意の型のシステム指定オブジェクトへのハンドル。
[in] PreviousMode
ハンドルを開いたスレッドの以前のプロセッサ モードを指定します。 カーネル ハンドルを閉じるには、このパラメーターを KernelMode に設定します。 ユーザー ハンドルを閉じるには、このパラメーターを UserMode に設定します。 これら 2 つのハンドルの種類の詳細については、「解説」を参照してください。
戻り値
呼び出しが成功した場合、ObCloseHandle はSTATUS_SUCCESSを返します。 考えられるエラー戻り値には、次の NTSTATUS コードが含まれます。
| リターン コード | 説明 |
|---|---|
| STATUS_INVALID_HANDLE | ハンドル が有効なハンドルではありません。 |
| STATUS_HANDLE_NOT_CLOSABLE | 呼び出し元のスレッドには、ハンドルを閉じるアクセス許可がありません。 |
注釈
カーネル モード ドライバーは 、ObCloseHandle を呼び出して、Windows カーネルによって作成された任意の種類のオブジェクトへのハンドルを閉じます。 ドライバーは、ハンドルが不要になったらすぐに開くすべてのハンドルを閉じる必要があります。
ObCloseHandle がオブジェクトのハンドルを閉じると、呼び出し元はハンドルを無効として扱い、ハンドルを使用してオブジェクトにアクセスしないようにする必要があります。 ただし、他のハンドルは同じオブジェクトで開いたままになる場合があります。 ObCloseHandle 呼び出し中に、システムはオブジェクトのハンドル数をデクリメントし、オブジェクトを削除できるかどうかを確認します。 システムは、オブジェクトのすべてのハンドルが閉じられ、オブジェクトへの参照カウントされたすべてのポインターが解放されるまで、オブジェクトを削除しません。
PreviousMode パラメーターは、閉じるハンドルがカーネル ハンドルかユーザー ハンドルかを指定します。 カーネル ハンドルを閉じるには、 PreviousMode を KernelMode に設定します。 ユーザー ハンドルを閉じるには、 PreviousMode を UserMode に設定します。
カーネル ハンドルは、システム スレッド、またはOBJ_KERNEL_HANDLE属性をハンドルに割り当てるカーネル モード ドライバーによって開かれるハンドルです。 (たとえば、 ZwCreateFile のOBJ_KERNEL_HANDLEの説明を参照してください)。カーネル モード ドライバーがプライベート使用用のハンドルを開き、このドライバーがユーザー モード スレッドのコンテキストで実行される場合、ドライバーは OBJ_KERNEL_HANDLE 属性を使用してハンドルを開く必要があります。 この属性を使用すると、ユーザー モード アプリケーションからハンドルにアクセスできなくなります。
ユーザー ハンドルは、ユーザー モード アプリケーション、またはユーザー モード スレッドのコンテキストで実行されるが、OBJ_KERNEL_HANDLE属性でハンドルを開かないカーネル モード ドライバーによって開かれるハンドルです。 ドライバーがユーザー モード アプリケーションで使用するユーザー ハンドルを作成する場合、ドライバーがアプリケーションの代わりにハンドルを閉じる必要があるエラーが発生した場合、ドライバーは ObCloseHandle を呼び出してハンドルを閉じます。
ZwClose ルーチンは ObCloseHandle に似ていますが、カーネル ハンドルのみを閉じることができます。 カーネル ハンドル hObject を閉じる呼び出し ZwClose(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
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h |
| Library | Ntoskrnl.lib |
| [DLL] | Ntoskrnl.exe |
| IRQL | PASSIVE_LEVEL |