ObDereferenceObjectWithTag マクロ (wdm.h)

  • [アーティクル]

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

  1. ObDereferenceObjectWithTag を呼び出します。

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

  3. 手順 2 で取得したハンドルを使用して ZwMakeTemporaryObject を呼び出します。

  4. 手順 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)

こちらもご覧ください

InitializeObjectAttributes

IoGetDeviceObjectPointer

ObDereferenceObject

ObDereferenceObjectDeferDeleteWithTag

ObReferenceObjectByHandleWithTag

ZwClose

ZwMakeTemporaryObject