ObReferenceObjectByHandleWithTag-Funktion (wdm.h)

Artikel
02/27/2024

Die ObReferenceObjectByHandleWithTag-Routine erhöht die Verweisanzahl des Objekts, das durch das angegebene Handle identifiziert wird, und schreibt einen Wert des Vier-Byte-Tags in das Objekt, um die Objektverweisablaufverfolgung zu unterstützen.

Syntax

NTSTATUS ObReferenceObjectByHandleWithTag(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [in]            ULONG                      Tag,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

Parameter

[in] Handle

Gibt ein geöffnetes Handle für ein Objekt an.

[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. 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. Es muss entweder UserMode oder KernelMode sein. Treiber sollten immer UserMode für Handles angeben, die sie aus dem Benutzeradressraum empfangen.

[in] Tag

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

[out] Object

Ein Zeiger auf eine Variable, in die die Routine einen Zeiger auf das -Objekt schreibt. In der folgenden Tabelle sind die Object-Zeigertypen aufgeführt, die durch die möglichen ObjectType-Parameterwerte festgelegt werden.

ObjectType-Parameter	Objektzeigertyp
*ExEventObjectType	PKEVENT
*ExSemaphoreObjectType	PKSEMAPHOR
*IoFileObjectType	PFILE_OBJECT
*PsProcessType	PEPROCESS oder PKPROCESS
*PsThreadType	PETHREAD oder PKTHREAD
*SeTokenObjectType	PACCESS_TOKEN
*TmEnlistmentObjectType	PKENLISTMENT
*TmResourceManagerObjectType	PKRESOURCEMANAGER
*TmTransactionManagerObjectType	PKTM
*TmTransactionObjectType	PKTRANSACTION

Die Strukturen, auf die die Zeigertypen verweisen, sind undurchsichtig, und Treiber können nicht auf die Strukturmember zugreifen. Da die Strukturen undurchsichtig sind, ist PEPROCESS äquivalent zu PKPROCESS und PETHREAD entspricht PKTHREAD.

[out, optional] HandleInformation

Treiber legen diesen Parameter auf NULL fest.

Rückgabewert

ObReferenceObjectByHandleWithTag 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, das durch den Handle-Parameter identifiziert wird.
STATUS_ACCESS_DENIED	Der Aufrufer verfügt nicht über die erforderlichen Zugriffsrechte für das Objekt.
STATUS_INVALID_HANDLE	Der angegebene Handle ist ungültig.

Hinweise

Diese Routine führt die Zugriffsüberprüfung des angegebenen Objekthandles durch. Wenn Zugriff gewährt werden kann, erhöht die Routine die Objektverweisanzahl und stellt einen Objektzeiger auf den Aufrufer bereit. 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.

ObReferenceObjectByHandleWithTag schließt oder ungültig das Objekthandle, das durch den Handle-Parameter angegeben wird. Wenn das Handle nicht mehr benötigt wird, kann der Aufrufer den Handle schließen, indem er die ZwClose-Routine aufruft.

Wenn der AccessMode-ParameterwertKernelMode ist, ist der angeforderte Zugriff immer zulässig. Wenn AccessModeUserMode ist, wird der angeforderte Zugriff mit den Zugriffsrechten verglichen, die der Aufrufer für das Objekt hat. Nur Treiber der höchsten Ebene können den UserMode-Wert für den AccessMode-Parameter sicher angeben.

Ab Windows 7, wenn AccessModeKernelMode ist und handle aus dem Benutzeradressraum empfangen wird, gibt driver verifier bugcheck C4, Subcode F6 aus.

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

Um eine Objektverweisablaufverfolgung in den Windows-Debugtools anzuzeigen, verwenden Sie die Debuggererweiterung !obtrace im Kernelmodus. Die Erweiterung !obtrace wurde 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	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport)