ObReferenceObjectByHandle 関数 (wdm.h)

ObReferenceObjectByHandle ルーチンは、オブジェクト ハンドルに対するアクセス検証を提供し、アクセスを許可できる場合は、オブジェクトの本体への対応するポインターを返します。

構文

NTSTATUS ObReferenceObjectByHandle(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

パラメーター

[in] Handle

オブジェクトの開いているハンドルを指定します。

[in] DesiredAccess

オブジェクトへのアクセスの要求された種類を指定します。 このフィールドの解釈は、オブジェクトの種類によって異なります。 一般的なアクセス権は使用しないでください。 詳細については、 ACCESS_MASKを参照してください。

[in, optional] ObjectType

オブジェクト型へのポインター。 ObjectType には、 *ExEventObjectType*ExSemaphoreObjectType*IoFileObjectType*PsProcessType*PsThreadType*SeTokenObjectType*TmEnlistmentObjectType*TmResourceManagerObjectType*TmTransactionManagerObjectType、または *TmTransactionObjectType を指定できます。

ObjectTypeNULL でない場合、オペレーティング システムは、指定されたオブジェクトの種類が、Handle で指定されたオブジェクトのオブジェクト型と一致することを確認します。

[in] AccessMode

アクセス チェックに使用するアクセス モードを指定します。 UserMode または KernelMode である必要があります。 ドライバーでは、ユーザー アドレス空間から受け取るハンドルに対して常に UserMode を指定する必要があります。

[out] Object

オブジェクトの本体へのポインターを受け取る変数へのポインター。 次の表に、ポインターの型を示します。

ObjectType パラメーター オブジェクト ポインターの型
*ExEventObjectType PKEVENT
*ExSemaphoreObjectType PKSEMAPHORE
*IoFileObjectType PFILE_OBJECT
*PsProcessType PEPROCESS または PKPROCESS
*PsThreadType PETHREAD または PKTHREAD
*SeTokenObjectType PACCESS_TOKEN
*TmEnlistmentObjectType PKENLISTMENT
*TmResourceManagerObjectType PKRESOURCEMANAGER
*TmTransactionManagerObjectType PKTM
*TmTransactionObjectType PKTRANSACTION

ポインター型が参照する構造体は不透明であり、ドライバーは構造体のメンバーにアクセスできません。 構造体は不透明であるため、PEPROCESS は PKPROCESS に相当し、PETHREAD は PKTHREAD に相当します。

[out, optional] HandleInformation

ドライバーは、これを NULL に設定します。

戻り値

ObReferenceObjectByHandle は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。 可能な戻り値には、次のエラー コードが含まれます。

リターン コード 説明
STATUS_OBJECT_TYPE_MISMATCH ObjectType パラメーターは、Handle パラメーターによって識別されるオブジェクトに対して間違ったオブジェクトの種類を指定します。
STATUS_ACCESS_DENIED 呼び出し元に、オブジェクトに対する要求されたアクセス権を付与することはできません。
STATUS_INVALID_HANDLE Handle パラメーターが有効なオブジェクト ハンドルではありません。

注釈

オブジェクト本体へのポインターは、オブジェクト テーブル エントリから取得され、 Object パラメーターを使用して呼び出し元に返されます。

AccessModeUserMode の場合、要求されたアクセスは、オブジェクトに付与されたアクセスと比較されます。 AccessModeKernelMode の場合、ハンドルはカーネル アドレス空間で発生する必要があります。

Windows 7 以降では、 AccessModeKernelMode で、ハンドルがユーザー アドレス空間から受信された場合、 ドライバー検証ツール はバグチェック C4、サブコード F6 を発行します。

呼び出しが成功すると、オブジェクト本体へのポインターが呼び出し元に返され、ポインター参照カウントがインクリメントされます。 このカウントをインクリメントすると、ポインターの参照中にオブジェクトが削除されなくなります。 呼び出し元は、オブジェクトで完了するとすぐに ObDereferenceObject で参照カウントをデクリメントする必要があります。

要件

   
サポートされている最小のクライアント Windows 2000 以降で使用できます。
対象プラットフォーム ユニバーサル
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 HwStorPortProhibitedDDIs(storport)IrqlObPassive(wdm)TargetRelationNeedsRef(wdm)

こちらもご覧ください

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer