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) |