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 を指定できます。

ObjectType が NULL でない場合、オペレーティング システムは、指定されたオブジェクトの種類が 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 パラメーターを使用して呼び出し元に返されます。

AccessMode が UserMode の場合、要求されたアクセスは、オブジェクトに対して付与されたアクセスと比較されます。 AccessMode が KernelMode の場合、ハンドルはカーネル アドレス空間で生成されます。

Windows 7 以降では、 AccessMode が KernelMode で、ハンドルがユーザー アドレス空間から受信された場合、 ドライバー検証ツール はバグチェック 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