ObReferenceObjectByPointerWithTag-Funktion (wdm.h)

Artikel
02/27/2024

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

Syntax

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           Tag
);

Parameter

[in] Object

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] DesiredAccess

Gibt die Zugriffstypen auf das Objekt an, das der Aufrufer anfordert. Dieser Parameter ist eine Bitmaske vom Typ ACCESS_MASK. Die Interpretation dieses Felds hängt vom Objekttyp ab. Verwenden Sie keine generischen Zugriffsrechte.

[in, optional] ObjectType

Ein Zeiger auf eine undurchsichtige Struktur, die den Objekttyp angibt. Dieser Parameter verweist auf eine OBJECT_TYPE-Struktur . Legen Sie ObjectType auf NULL oder auf einen der folgenden Zeigerwerte fest, die in der Wdm.h-Headerdatei deklariert werden: *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType oder *TmTransactionObjectType. Dieser Parameter kann NULL sein, wenn AccessModeKernelMode ist. Wenn ObjectType nicht NULL ist, überprüft die Routine, ob der angegebene Objekttyp mit dem Objekttyp des Objekts übereinstimmt, den der Handle-Parameter angibt.

[in] AccessMode

Gibt den Zugriffsmodus an, der für die Zugriffsprüfung verwendet werden soll. Legen Sie diesen Parameter auf einen der folgenden MODE-Enumerationswerte fest:

Usermode
KernelMode

Treiber auf niedrigerer Ebene sollten KernelMode angeben.

[in] Tag

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

Rückgabewert

ObReferenceObjectByPointerWithTag gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_OBJECT_TYPE_MISMATCH	Der ObjectType-Parameter gibt den falschen Objekttyp für das Objekt an, auf das der Object-Parameter verweist, oder ObjectType ist NULL , aber AccessMode ist UserMode.

Hinweise

Diese Routine führt die Zugriffsüberprüfung des angegebenen Objekts durch. Wenn Zugriff gewährt werden kann, erhöht die Routine die Objektverweisanzahl. Diese Inkrementierung verhindert, dass das Objekt gelöscht wird, während der Aufrufer das Objekt verwendet. Wenn das Objekt nicht mehr benötigt wird, sollte der Aufrufer die Verweisanzahl verringern, indem die Routine ObDereferenceObjectWithTag oder ObDereferenceObjectDeferDeleteWithTag aufgerufen wird.

Weitere Informationen zu Objektverweise finden Sie unter Lebenszyklus eines Objekts.

Die ObReferenceObjectByPointer-Routine ähnelt ObReferenceObjectByPointerWithTag, mit der Ausnahme, dass der Aufrufer kein benutzerdefiniertes Tag in ein Objekt schreiben kann. In Windows 7 und höheren Versionen von Windows schreibt ObReferenceObjectByPointer immer einen Standardtagwert ('tlfD') in das Objekt. Ein Aufruf von ObReferenceObjectByPointer hat die gleiche Auswirkung wie ein Aufruf von ObReferenceObjectByPointerWithTag , 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	Universell
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport)