ObReferenceObjectWithTag マクロ (wdm.h)

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

構文

void ObReferenceObjectWithTag(
  [in]  Object,
  [in]  Tag
);

パラメーター

[in] Object

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

[in] Tag

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

戻り値

なし

解説

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

ObReferenceObjectWithTag は、指定したオブジェクトに対するアクセス チェックを行わずに、オブジェクトのポインター参照カウントをインクリメントするだけです。 これに対し、 ObReferenceObjectByHandleWithTag ルーチンと ObReferenceObjectByPointerWithTag ルーチンは、呼び出し元がオブジェクトに対して必要なアクセス権を持っていることを確認し、呼び出し元にこれらの権限がない場合は失敗します。

ObReferenceObjectWithTag 呼び出しは、少なくともドライバーが ObDereferenceObjectWithTag ルーチンを呼び出すか、オブジェクトを閉じるまで、指定されたオブジェクトの削除を防ぎます。 オブジェクトが不要になった後、ドライバーは ObDereferenceObjectWithTag を呼び出して、オブジェクトへの参照を削除する必要があります。

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

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

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

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

要件

こちらもご覧ください

ObDereferenceObjectWithTag

ObReferenceObject

ObReferenceObjectByHandleWithTag

ObReferenceObjectByPointerWithTag