ObDereferenceObjectWithTag マクロ (wdm.h)

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

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

構文

void ObDereferenceObjectWithTag(
  [in]  a,
  [in]  t
);

パラメーター

[in] a

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

[in] t

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

戻り値

なし

解説

ObDereferenceObjectWithTag は、システムで使用するために予約されている値を返します。ドライバーは、この値を VOID として扱う必要があります。

カーネルモードドライバーは、オブジェクトの参照カウントを 1 つずつデクリメントするには、このルーチンを呼び出します。オブジェクトが一時として作成され (つまり、オブジェクトの作成時にOBJ_PERMANENT フラグが指定されなかった)、参照カウントが 0 に達すると、オブジェクトマネージャーはオブジェクトを削除します。

オブジェクトの参照カウントが 0 に達すると、カーネルモードコンポーネントはオブジェクトを削除できます。ただし、ドライバーは、作成したオブジェクトのみを削除できます。ドライバーは、作成しなかったオブジェクトを削除しようとしないでください。

オブジェクトは、OBJ_PERMANENT オブジェクト属性フラグを指定して作成された場合、 永続的 です。 (オブジェクト属性の詳細については、「 InitializeObjectAttributes」を参照してください)。永続オブジェクトは最初の参照カウント 1 で作成されるため、ドライバーがオブジェクトへの最後の参照を削除してもオブジェクトは削除されません。

削除する永続的なオブジェクトを準備するために、ドライバーは ZwMakeTemporaryObject ルーチンを呼び出して、オブジェクトを一時的なものにすることができます。ドライバーは、作成した永続的なオブジェクトのみを削除する必要があります。永続的なオブジェクトを削除するには、次の手順に従います。

ObDereferenceObjectWithTag を呼び出します。
オブジェクトへのハンドルを取得します。必要に応じて、適切な ZwOpenXxx または ZwCreateXxx ルーチンを呼び出して、オブジェクトハンドルを取得します。
手順 2 で取得したハンドルを使用して ZwMakeTemporaryObject を呼び出します。
手順 2 で取得したハンドルを使用して ZwClose を呼び出します。

現在のスレッドによるオブジェクトの即時削除によってデッドロックが発生する可能性がある場合は、オブジェクトを逆参照するために ObDereferenceObjectWithTag を呼び出さないでください。代わりに、 ObDereferenceObjectDeferDeleteWithTag ルーチンを呼び出して、オブジェクトを逆参照します。

たとえば、ドライバースタック上の上位レベルのドライバーがロックを保持しているときに 、ObDereferenceObjectWithTag を使用してカーネルトランザクションマネージャー (KTM) オブジェクトを逆参照すると、このようなデッドロックが発生する可能性があります。

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

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

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)