ObOpenObjectByPointer 関数 (ntifs.h)
ObOpenObjectByPointer 関数は、ポインターによって参照されるオブジェクトを開き、オブジェクトへのハンドルを返します。
構文
NTSTATUS ObOpenObjectByPointer(
[in] PVOID Object,
[in] ULONG HandleAttributes,
[in, optional] PACCESS_STATE PassedAccessState,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_TYPE ObjectType,
[in] KPROCESSOR_MODE AccessMode,
[out] PHANDLE Handle
);
パラメーター
[in] Object
開くオブジェクトへのポインター。
[in] HandleAttributes
オブジェクト ハンドルに必要な属性を指定するフラグのビットマスク。 呼び出し元がシステム プロセス コンテキストで実行されていない場合、これらのフラグにはOBJ_KERNEL_HANDLEが含まれている必要があります。 このパラメーターは省略可能で、0 にすることができます。 それ以外の場合は、次の値の 1 つ以上の OR'ed の組み合わせです。
| 旗 | 意味 |
|---|---|
| OBJ_EXCLUSIVE | オブジェクトは、排他アクセスのために開かれます。 このフラグが設定され、ObOpenObjectByPointer の呼び出しが成功した場合、オブジェクトは共有できず、ハンドルが閉じられるまで再度開くことはできません。 このフラグは、OBJ_INHERIT フラグと互換性がありません。 このフラグは、ファイル オブジェクトでは無効です。 |
| OBJ_FORCE_ACCESS_CHECK | オブジェクトがカーネル モードで開かれている場合でも、すべてのアクセス チェックがオブジェクトに適用されます。 このフラグを指定すると、AccessMode パラメーターの値は無視されます。 |
| OBJ_INHERIT | ハンドルは、現在のプロセスの子プロセスによって継承できます。 このフラグは、OBJ_EXCLUSIVE フラグと互換性がありません。 |
| OBJ_KERNEL_HANDLE | ハンドルにはカーネル モードでのみアクセスできます。 呼び出し元がシステム プロセス コンテキストで実行されていない場合は、このフラグを指定する必要があります。 |
[in, optional] PassedAccessState
オブジェクトのサブジェクト コンテキスト、許可されたアクセスの種類、残りの必要なアクセスの種類を含む ACCESS_STATE 構造体へのポインター。 このパラメーターは省略可能であり、NULL にすることができます。 ディスパッチの作成ルーチンでは、このポインターは IrpSp->Parameters.Create.SecurityContext->AccessStateにあります。IrpSp は IRP 内の呼び出し元独自のスタック位置へのポインターです。 (詳細については、IRP_MJ_CREATEを参照してください。
[in] DesiredAccess
オブジェクトへの必要なアクセスを指定する値を ACCESS_MASK します。 このパラメーターは省略可能で、0 にすることができます。
[in, optional] ObjectType
オブジェクト型へのポインター。 AccessMode の値が KernelMode 場合、このパラメーターは省略可能であり、NULL にすることができます。 それ以外の場合は、*ExEventObjectType、*ExSemaphoreObjectType、*IoFileObjectType、*PsThreadType、*SeTokenObjectType、または *CmKeyObjectTypeのいずれかである必要があります。
手記
SeTokenObjectType オブジェクト型は Windows XP を使用したスターリングがサポートされ、CmKeyObjectType オブジェクト型は Windows 7 を参照してサポートされています。
[in] AccessMode
アクセス チェックに使用するアクセス モード。 このパラメーターは必須であり、UserMode または KernelMode する必要があります。
AccessMode が KernelMode されている場合、システムは、以前にドライバーを設定した制限付きアクセスに関係なく、要求されたアクセスを常に許可します (たとえば、以前の呼び出しでアクセスが制限された POB_PRE_OPERATION_CALLBACK コールバック)。
AccessMode が UserMode されている場合、要求されたアクセスはオブジェクトに対して付与されたアクセスと比較されます。
[out] Handle
オブジェクトへのハンドルを受け取る呼び出し元によって割り当てられた変数へのポインター。
戻り値
ObOpenObjectByPointer は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。
| リターン コード | 形容 |
|---|---|
| STATUS_ACCESS_DENIED | 呼び出し元には、オブジェクトのハンドルを開くために必要なアクセス権がありませんでした。 これはエラー コードです。 |
| STATUS_INSUFFICIENT_RESOURCES | ObOpenObjectByPointer プール割り当てエラーが発生しました。 これはエラー コードです。 |
| STATUS_INVALID_PARAMETER | HandleAttributes パラメーターに無効なフラグ値が指定されました。 これはエラー コードです。 |
| STATUS_OBJECT_TYPE_MISMATCH | Object パラメーターが指すオブジェクトが、ObjectType パラメーターで指定された型ではありません。 これはエラー コードです。 |
| STATUS_PRIVILEGE_NOT_HELD | 呼び出し元には、DesiredAccess パラメーターで指定されたアクセス権を持つハンドルを作成するために必要な特権がありませんでした。 これはエラー コードです。 |
| STATUS_QUOTA_EXCEEDED | 呼び出し元は、メモリ クォータがオブジェクト ハンドルを割り当てるのに十分ではないプロセスのコンテキストで実行されています。 これはエラー コードです。 |
| STATUS_UNSUCCESSFUL | オブジェクト ハンドルを作成できませんでした。 これはエラー コードです。 |
備考
Object パラメーターがファイル オブジェクト (つまり、FILE_OBJECT構造体) を指している場合、ObOpenObjectByPointer は、ファイル オブジェクトに対して少なくとも 1 つのハンドルが作成された後にのみ呼び出すことができます。 呼び出し元は、Object パラメーターが指 FILE_OBJECT構造体のメンバー フラグを確認できます。 FO_HANDLE_CREATED フラグが設定されている場合は、ファイル オブジェクトに対して 1 つ以上のハンドルが作成されているため、obOpenObjectByPointer 呼び出しても安全です。
ObOpenObjectByPointer 呼び出すことによって取得されたハンドルは、最終的に ZwClose呼び出すことによって解放する必要があります。
システム プロセス以外のプロセス コンテキストで実行されるドライバー ルーチンは、HandleAttributes パラメーターにOBJ_KERNEL_HANDLE フラグを設定する必要があります。 これにより、ObOpenObjectByPointer によって返されるハンドルの使用が、カーネル モードで実行されているプロセスに制限されます。 それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。
必要条件
| 要件 | 価値 |
|---|---|
| ターゲット プラットフォーム の | 万国 |
| ヘッダー | ntifs.h (Ntifs.h を含む) |
| ライブラリ | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |