ObReferenceObjectByHandle-Funktion (wdm.h)

  • Artikel

Die ObReferenceObjectByHandle-Routine ermöglicht die Zugriffsüberprüfung für das Objekthandle und gibt den entsprechenden Zeiger auf den Objekttext zurück, wenn der Zugriff gewährt werden kann.

Syntax

NTSTATUS ObReferenceObjectByHandle(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [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 angeforderten Zugriffstypen auf das Objekt an. Die Interpretation dieses Felds ist vom Objekttyp abhängig. Verwenden Sie keine generischen Zugriffsrechte. Weitere Informationen finden Sie unter ACCESS_MASK.

[in, optional] ObjectType

Zeiger auf den Objekttyp. ObjectType kann *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType oder *TmTransactionObjectType sein.

Wenn ObjectType nicht NULL ist, überprüft das Betriebssystem, ob der angegebene Objekttyp mit dem Objekttyp des Von Handle angegebenen Objekts übereinstimmt.

[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.

[out] Object

Zeiger auf eine Variable, die einen Zeiger auf den Textkörper des Objekts empfängt. Die folgende Tabelle enthält die Zeigertypen.

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 dies auf NULL fest.

Rückgabewert

ObReferenceObjectByHandle gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Rückgabewerte sind die folgenden Fehlercodes:

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 Dem Aufrufer können die angeforderten Zugriffsrechte für das Objekt nicht gewährt werden.
STATUS_INVALID_HANDLE Der Handle-Parameter ist kein gültiges Objekthandle.

Hinweise

Ein Zeiger auf den Objekttext wird aus dem Objekttabelleneintrag abgerufen und mithilfe des Object-Parameters an den Aufrufer zurückgegeben.

Wenn AccessModeUserMode ist, wird der angeforderte Zugriff mit dem gewährten Zugriff für das Objekt verglichen. Wenn AccessModeKernelMode ist, sollte das Handle aus dem Kerneladressraum stammen.

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

Wenn der Aufruf erfolgreich ist, wird ein Zeiger auf den Objekttext an den Aufrufer zurückgegeben, und die Anzahl der Zeigerverweis wird erhöht. Durch Erhöhen dieser Anzahl wird verhindert, dass das Objekt gelöscht wird, während auf den Zeiger verwiesen wird. Der Aufrufer muss die Verweisanzahl mit ObDereferenceObject dekrementieren, sobald dies mit dem Objekt erfolgt ist.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar ab Windows 2000.
Zielplattform Universell
Header wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDDIs(storport), IrqlObPassive(wdm), TargetRelationNeedsRef(wdm)

Weitere Informationen

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer