ObOpenObjectByPointer-Funktion (ntifs.h)

Artikel
02/07/2025

Die ObOpenObjectByPointer--Funktion öffnet ein Objekt, auf das von einem 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 einem oder mehreren der folgenden Werte.

Flagge	Bedeutung
OBJ_EXCLUSIVE	Das Objekt soll für exklusiven Zugriff geöffnet werden. Wenn dieses Flag festgelegt ist und der Aufruf von ObOpenObjectByPoint er erfolgreich ausgeführt wird, kann das Objekt nicht freigegeben und erst wieder geöffnet werden, wenn das Handle geschlossen wird. Dieses Flag ist nicht mit dem OBJ_INHERIT Flag 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 ist, 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

Zeigen Sie auf eine ACCESS_STATE Struktur, die den Betreffkontext des Objekts enthält, Zugriffstypen gewährt und die gewünschten Zugriffstypen erhalten. Dieser Parameter ist optional und kann NULL sein. In einer Create Dispatch Routine kann dieser Zeiger in IrpSp->Parameters.Create.SecurityContext->AccessStategefunden werden, wobei IrpSp- ein Zeiger auf den eigenen Stapelspeicherort des Aufrufers im 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 AccessMode-KernelMode-ist, ist dieser Parameter optional und kann NULL sein. Andernfalls muss es sich um *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectType, oder *CmKeyObjectType.

Anmerkung

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

[in] AccessMode

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

Wenn AccessMode-KernelMode-ist, ermöglicht das System immer den angeforderten Zugriff unabhängig von zuvor festgelegtem eingeschränktem Zugriff (z. B. zugriff eingeschränkten in einem vorherigen Aufruf an POB_PRE_OPERATION_CALLBACK Rückruf).
Wenn AccessMode-UserMode-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 für das Objekt empfängt.

Rückgabewert

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

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

Bemerkungen

Wenn der parameter Object auf ein Dateiobjekt verweist (d. h. eine FILE_OBJECT-Struktur), 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 parameter Object verweist. Wenn das FO_HANDLE_CREATED Flag festgelegt ist, bedeutet dies, dass mindestens ein Handles für das Dateiobjekt erstellt wurde, sodass es sicher ist, ObOpenObjectByPointeraufzurufen.

Jedes Handle, das durch Aufrufen von ObOpenObjectByPointer abgerufen wird, muss schließlich durch Aufrufen von ZwClosefreigegeben 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 Handle auf Prozesse beschränkt, die im Kernelmodus ausgeführt werden. Andernfalls kann über den Prozess, in dem der Treiber ausgeführt wird, auf das Handle zugegriffen werden kann.