ObOpenObjectByPointer-Funktion (ntifs.h)

Artikel
02/29/2024

Die ObOpenObjectByPointer-Funktion öffnet ein Objekt, auf das durch einen Zeiger verwiesen wird, und gibt ein Handle an das Objekt zurück.

Syntax

NTSTATUS ObOpenObjectByPointer(
  [in]           PVOID           Object,
  [in]           ULONG           HandleAttributes,
  [in, optional] PACCESS_STATE   PassedAccessState,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [out]          PHANDLE         Handle
);

Parameter

[in] Object

Zeiger auf das zu öffnende Objekt.

[in] HandleAttributes

Bitmaske von Flags, die die gewünschten Attribute für das Objekthandle angeben. Wenn der Aufrufer nicht im Systemprozesskontext ausgeführt wird, müssen diese Flags OBJ_KERNEL_HANDLE enthalten. Dieser Parameter ist optional und kann null sein. Andernfalls handelt es sich um eine OR'ed-Kombination aus mindestens einem der folgenden Werte.

Flag	Bedeutung
OBJ_EXCLUSIVE	Das Objekt soll für den exklusiven Zugriff geöffnet werden. Wenn dieses Flag festgelegt ist und der Aufruf von ObOpenObjectByPointer erfolgreich ist, kann das Objekt nicht freigegeben werden und kann erst wieder geöffnet werden, wenn das Handle geschlossen ist. Dieses Flag ist mit dem OBJ_INHERIT-Flag nicht kompatibel. Dieses Flag ist für Dateiobjekte ungültig.
OBJ_FORCE_ACCESS_CHECK	Alle Zugriffsprüfungen müssen für das Objekt erzwungen werden, auch wenn das Objekt im Kernelmodus geöffnet wird. Wenn dieses Flag angegeben wird, wird der Wert des AccessMode-Parameters ignoriert.
OBJ_INHERIT	Das Handle kann von untergeordneten Prozessen des aktuellen Prozesses geerbt werden. Dieses Flag ist mit dem OBJ_EXCLUSIVE-Flag nicht kompatibel.
OBJ_KERNEL_HANDLE	Auf das Handle kann nur im Kernelmodus zugegriffen werden. Dieses Flag muss angegeben werden, wenn der Aufrufer nicht im Systemprozesskontext ausgeführt wird.

[in, optional] PassedAccessState

Zeiger auf eine ACCESS_STATE-Struktur , die den Betreffkontext des Objekts, gewährte Zugriffstypen und die verbleibenden gewünschten Zugriffstypen enthält. Dieser Parameter ist optional und kann NULL sein. In einer Create Dispatch-Routine finden Sie diesen Zeiger in IrpSp-Parameters.Create.SecurityContext-AccessState>>, wobei IrpSp ein Zeiger auf den eigenen Stapelspeicherort des Aufrufers in der IRP ist. (Weitere Informationen finden Sie unter IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK Wert, der den gewünschten Zugriff auf das Objekt angibt. Dieser Parameter ist optional und kann null sein.

[in, optional] ObjectType

Zeiger auf den Objekttyp. Wenn der Wert von AccessModeKernelMode ist, ist dieser Parameter optional und kann NULL sein. Andernfalls muss es entweder *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectType oder *CmKeyObjectType sein.

Hinweis

Der SeTokenObjectType-Objekttyp wird mit Windows XP unterstützt, und der CmKeyObjectType-Objekttyp wird mit Windows 7 unterstützt.

[in] AccessMode

Zugriffsmodus, der für die Zugriffsprüfung verwendet werden soll. Dieser Parameter ist erforderlich und muss entweder UserMode oder KernelMode sein:

Wenn AccessModeKernelMode ist, lässt das System immer den angeforderten Zugriff zu, unabhängig von einem eingeschränkten Zugriff, der zuvor einen Treiber festgelegt hat (z. B. zugriffseinschränkt in einem vorherigen Aufruf POB_PRE_OPERATION_CALLBACK Rückrufs).
Wenn AccessModeUserMode ist, wird der angeforderte Zugriff mit dem gewährten Zugriff für das Objekt verglichen.

[out] Handle

Zeiger auf eine vom Aufrufer zugewiesene Variable, die ein Handle auf das Objekt empfängt.

Rückgabewert

ObOpenObjectByPointer gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert zurück, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_ACCESS_DENIED	Der Aufrufer hatte nicht den erforderlichen Zugriff, um ein Handle für das Objekt zu öffnen. Dies ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer ist ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Im HandleAttributes-Parameter wurde ein ungültiger Flagwert angegeben. Dies ist ein Fehlercode.
STATUS_OBJECT_TYPE_MISMATCH	Das Objekt, auf das vom Object-Parameter verwiesen wird, war nicht vom Typ, der im ObjectType-Parameter angegeben ist. Dies ist ein Fehlercode.
STATUS_PRIVILEGE_NOT_HELD	Der Aufrufer verfügte nicht über die erforderliche Berechtigung zum Erstellen eines Handles mit dem im DesiredAccess-Parameter angegebenen Zugriff. Dies ist ein Fehlercode.
STATUS_QUOTA_EXCEEDED	Der Aufrufer wird im Kontext eines Prozesses ausgeführt, dessen Arbeitsspeicherkontingent nicht ausreicht, um das Objekthandle zuzuweisen. Dies ist ein Fehlercode.
STATUS_UNSUCCESSFUL	Das Objekthandle konnte nicht erstellt werden. Dies ist ein Fehlercode.

Hinweise

Wenn der Object-Parameter auf ein Dateiobjekt (d. h. eine FILE_OBJECT-Struktur) verweist, kann ObOpenObjectByPointer nur aufgerufen werden, nachdem mindestens ein Handle für das Dateiobjekt erstellt wurde. Aufrufer können das Flags-Element der FILE_OBJECT Struktur überprüfen, auf die der Object-Parameter verweist. Wenn das FO_HANDLE_CREATED-Flag festgelegt ist, bedeutet dies, dass mindestens ein Handle für das Dateiobjekt erstellt wurde, sodass es sicher ist, ObOpenObjectByPointer aufzurufen.

Jedes Handle, das durch aufrufen von ObOpenObjectByPointer abgerufen wird, muss schließlich durch Aufrufen von ZwClose freigegeben werden.

Treiberroutinen, die in einem anderen Prozesskontext als dem des Systemprozesses ausgeführt werden, müssen das OBJ_KERNEL_HANDLE-Flag im HandleAttributes-Parameter festlegen. Dadurch wird die Verwendung des von ObOpenObjectByPointer zurückgegebenen Handles auf Prozesse eingeschränkt, die im Kernelmodus ausgeführt werden. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen.