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