ObReferenceObjectByHandleWithTag-Funktion (wdm.h)

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.

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:

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

Weitere Informationen

ACCESS_MASK

OBJECT_TYPE

ObDereferenceObjectDeferDeleteWithTag

ObDereferenceObjectWithTag

ObReferenceObjectByHandle

ZwClose