ObReferenceObjectByPointerWithTag 関数 (wdm.h)

[アーティクル]
03/18/2023

ObReferenceObjectByPointerWithTag ルーチンは、指定したオブジェクトの参照カウントをインクリメントし、オブジェクト参照トレースをサポートするために 4 バイトのタグ値をオブジェクトに書き込みます。

構文

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           Tag
);

パラメーター

[in] Object

オブジェクトへのポインター。呼び出し元は、オブジェクトを作成するとき、またはオブジェクトを開いた後の ObReferenceObjectByHandleWithTag ルーチンの以前の呼び出しから、このポインターを取得します。

[in] DesiredAccess

呼び出し元が要求するオブジェクトへのアクセスの種類を指定します。このパラメーターは、 ACCESS_MASK型のビットマスクです。このフィールドの解釈は、オブジェクトの種類によって異なります。汎用アクセス権は使用しないでください。

[in, optional] ObjectType

オブジェクトの種類を指定する不透明な構造体へのポインター。このパラメーターは、OBJECT_TYPE 構造体を指します。 ObjectType を NULL に設定するか、Wdm.h ヘッダーファイルで宣言されているポインター値 (*ExEventObjectType、*ExSemaphoreObjectType、*IoFileObjectType、*PsProcessType、*PsThreadType、*SeTokenObjectType、*TmEnlistmentObjectType、*TmResourceManagerObjectType、*TmTransactionManagerObjectType、または *TmTransactionObjectType) のいずれかに設定します。 AccessMode が KernelMode の場合、このパラメーターは NULL にすることができます。 ObjectType が NULL でない場合、ルーチンは、指定されたオブジェクト型が Handle パラメーターで指定されたオブジェクトのオブジェクト型と一致することを確認します。

[in] AccessMode

アクセスチェックに使用するアクセスモードを示します。このパラメーターを、次のいずれかの MODE 列挙値に設定します。

UserMode
KernelMode

下位レベルのドライバーでは 、KernelMode を指定する必要があります。

[in] Tag

4 バイトのカスタムタグ値を指定します。詳細については、「解説」を参照してください。

戻り値

ObReferenceObjectByPointerWithTag は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。考えられるエラーの戻り値は次のとおりです。

リターンコード	説明
STATUS_OBJECT_TYPE_MISMATCH	ObjectType パラメーターは、Object パラメーターが指すオブジェクトの間違ったオブジェクト型を指定します。ObjectType は NULL ですが、AccessMode は UserMode です。

注釈

このルーチンは、指定されたオブジェクトの検証にアクセスします。アクセスを許可できる場合、ルーチンはオブジェクト参照カウントをインクリメントします。この増分により、呼び出し元がオブジェクトを使用している間にオブジェクトが削除されなくなります。オブジェクトが不要になったら、呼び出し元は ObDereferenceObjectWithTag ルーチンまたは ObDereferenceObjectDeferDeleteWithTag ルーチンを呼び出して、参照カウントをデクリメントする必要があります。

オブジェクト参照の詳細については、「オブジェクトのライフサイクル」を参照してください。

ObReferenceObjectByPointer ルーチンは ObReferenceObjectByPointerWithTag に似ていますが、呼び出し元がオブジェクトにカスタムタグを書き込むのを有効にしない点が例外です。 Windows 7 以降のバージョンの Windows では、 ObReferenceObjectByPointer は常に既定のタグ値 ('tlfD') をオブジェクトに書き込みます。 ObReferenceObjectByPointer の呼び出しは、Tag = 'tlfD' を指定する ObReferenceObjectByPointerWithTag の呼び出しと同じ効果があります。

Windows デバッグツールでオブジェクト参照トレースを表示するには、!obtrace カーネルモードデバッガー拡張機能を使用します。 Windows 7 では、オブジェクト参照トレースが有効になっている場合、 !obtrace 拡張機能が拡張され、オブジェクト参照タグが表示されます。既定では、オブジェクト参照トレースはオフになっています。グローバルフラグエディター (Gflags) を使用して、オブジェクト参照トレースを有効にします。詳細については、「タグを使用したオブジェクト参照トレース」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 7 以降のバージョンの Windows オペレーティングシステムで使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h、Fltkernel.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport)