ObReferenceObjectByPointerWithTag 関数 (wdm.h)
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) |