ObReferenceObjectByPointerWithTag-Funktion (wdm.h)
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) |