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構造体の Flags メンバーをチェックできます。 FO_HANDLE_CREATED フラグが設定されている場合は、ファイル オブジェクトに対して 1 つ以上のハンドルが作成されているため、 ObOpenObjectByPointer を呼び出しても問題ありません。
ObOpenObjectByPointer を呼び出して取得したハンドルは、最終的に ZwClose を呼び出して解放する必要があります。
システム プロセス以外のプロセス コンテキストで実行されるドライバー ルーチンでは、 HandleAttributes パラメーターに OBJ_KERNEL_HANDLE フラグを設定する必要があります。 これにより、 ObOpenObjectByPointer によって返されるハンドルの使用が、カーネル モードで実行されているプロセスに制限されます。 それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |