ObDereferenceObjectWithTag-Makro (wdm.h)

Artikel
03/01/2024

Die ObDereferenceObjectWithTag-Routine dekrementiert die Verweisanzahl des angegebenen Objekts und schreibt einen Tagwert mit vier Byte in das Objekt, um die Objektverweisablaufverfolgung zu unterstützen.

Syntax

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

Parameter

[in] a

Ein Zeiger auf das -Objekt. Der Aufrufer ruft diesen Zeiger entweder beim Erstellen des Objekts oder von einem vorherigen Aufruf der ObReferenceObjectByHandleWithTag-Routine ab, nachdem das Objekt geöffnet wurde.

[in] t

Gibt einen benutzerdefinierten Tagwert mit vier Byte an. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Keine

Bemerkungen

ObDereferenceObjectWithTag gibt einen Wert zurück, der für die Systemverwendung reserviert ist. Treiber müssen diesen Wert als VOID behandeln.

Ein Kernelmodustreiber ruft diese Routine auf, um die Verweisanzahl eines Objekts um eins zu verringern. Wenn das Objekt als temporär erstellt wurde (d. h. das OBJ_PERMANENT Flag wurde beim Erstellen des Objekts nicht angegeben), und die Verweisanzahl 00 erreicht, löscht der Objekt-Manager das Objekt.

Wenn die Verweisanzahl für ein Objekt 0 erreicht, kann eine Kernelmoduskomponente das Objekt löschen. Ein Treiber kann jedoch nur die objekte löschen, die er erstellt hat, und ein Treiber sollte niemals versuchen, ein objekt zu löschen, das er nicht erstellt hat.

Ein Objekt ist dauerhaft , wenn es mit dem angegebenen OBJ_PERMANENT-Attributflag erstellt wurde. (Weitere Informationen zu Objektattributen finden Sie unter InitializeObjectAttributes.) Ein permanentes Objekt wird mit einer anfänglichen Verweisanzahl von 1 erstellt, sodass das Objekt nicht gelöscht wird, wenn der Treiber seinen letzten Verweis auf das Objekt entfernt.

Um ein permanentes Objekt vorzubereiten, das gelöscht werden soll, kann ein Treiber die ZwMakeTemporaryObject-Routine aufrufen, um das Objekt temporär zu machen. Ein Treiber sollte nur ein permanentes Objekt löschen, das er erstellt hat. Führen Sie die folgenden Schritte aus, um ein permanentes Objekt zu löschen:

Rufen Sie ObDereferenceObjectWithTag auf.
Rufen Sie das Handle für das -Objekt ab. Rufen Sie bei Bedarf die entsprechende ZwOpenXxx - oder ZwCreateXxx-Routine auf, um das Objekthandle abzurufen.
Rufen Sie ZwMakeTemporaryObject mit dem in Schritt 2 abgerufenen Handle auf.
Rufen Sie ZwClose mit dem in Schritt 2 abgerufenen Handle auf.

Wenn das sofortige Löschen eines Objekts durch den aktuellen Thread zu einem Deadlock führen kann, rufen Sie ObDereferenceObjectWithTag nicht auf, um das Objekt zu dereferenzieren. Rufen Sie stattdessen die Routine ObDereferenceObjectDeferDeleteWithTag auf, um das Objekt zu deferieren.

Ein solcher Deadlock kann beispielsweise auftreten, wenn ObDereferenceObjectWithTag verwendet wird, um ein KernelTransaktions-Manager-Objekt (KTM) zu deferieren, wenn ein höherstufiger Treiber auf dem Treiberstapel eine Sperre hält.

Weitere Informationen zu Objektverweise finden Sie unter Lebenszyklus eines Objekts.

Die ObDereferenceObject-Routine ähnelt ObDereferenceObjectWithTag, mit der Ausnahme, dass der Aufrufer kein benutzerdefiniertes Tag in ein Objekt schreiben kann. In Windows 7 und höheren Versionen von Windows schreibt ObDereferenceObject immer einen Standardwert ('tlfD') in das Objekt. Ein Aufruf von ObDereferenceObject hat die gleiche Auswirkung wie ein Aufruf von ObDereferenceObjectWithTag , der Tag = 'tlfD' angibt.

Um eine Objektverweisablaufverfolgung in den Windows-Debugtools anzuzeigen, verwenden Sie die Debuggererweiterung !obtrace im Kernelmodus. In Windows 7 wird die Erweiterung !obtrace erweitert, um Objektverweistags anzuzeigen, wenn die Objektverweisablaufverfolgung aktiviert ist. Standardmäßig ist die Objektverweisablaufverfolgung deaktiviert. Verwenden Sie den Global Flags Editor (Gflags), um die Objektverweisablaufverfolgung zu aktivieren. Weitere Informationen finden Sie unter Objektverweisablaufverfolgung mit Tags.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 7 und höheren Versionen des Windows-Betriebssystems.
Zielplattform	Desktop
Kopfzeile	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport)