IoGetDeviceObjectPointer-Funktion (wdm.h)

Artikel
08/08/2023

Die IoGetDeviceObjectPointer-Routine gibt einen Zeiger auf das oberste Objekt im Stapel des benannten Geräteobjekts und einen Zeiger auf das entsprechende Dateiobjekt zurück, wenn der angeforderte Zugriff auf die Objekte gewährt werden kann.

Syntax

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

Parameter

[in] ObjectName

Zeiger auf einen Puffer, der eine Unicode-Zeichenfolge enthält, die dem Namen des Geräteobjekts entspricht.

[in] DesiredAccess

Gibt den ACCESS_MASK Wert an, der den gewünschten Zugriff darstellt. In der Regel ist DesiredAccess FILE_READ_DATA. Selten werden die FILE_WRITE_DATA oder FILE_ALL_ACCESS Zugriffsrechte angegeben.

[out] FileObject

Zeiger auf das Dateiobjekt, das das entsprechende Geräteobjekt darstellt, im Benutzermoduscode, wenn der Aufruf erfolgreich ist.

[out] DeviceObject

Zeiger auf das Geräteobjekt, das das benannte logische, virtuelle oder physische Gerät darstellt, wenn der Aufruf erfolgreich ist.

Rückgabewert

IoGetDeviceObjectPointer gibt bei erfolgreicher Ausführung STATUS_SUCCESS zurück. Mögliche Fehlerrückgabewerte sind die folgenden status-Codes:

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

Hinweise

IoGetDeviceObjectPointer stellt eine "Verbindung" zwischen dem Aufrufer und dem nächstniedrigen Treiber her. Ein erfolgreicher Aufrufer kann den zurückgegebenen Geräteobjektzeiger verwenden, um seine eigenen Geräteobjekte zu initialisieren. Es kann auch als Argument für IoAttachDeviceToDeviceStack, IoCallDriver und jede Routine verwendet werden, die IRPs für niedrigere Treiber erstellt. Der zurückgegebene Zeiger ist ein erforderliches Argument für IoCallDriver.

Diese Routine gibt auch einen Zeiger auf das entsprechende Dateiobjekt zurück. Beim Entladen kann ein Treiber den Rückschluss auf das Dateiobjekt ausführen, um das Geräteobjekt indirekt zu deferencieren. Dazu ruft der Treiber ObDereferenceObject aus seiner Unload-Routine auf und übergibt den von IoGetDeviceObjectPointer zurückgegebenen Dateiobjektzeiger. Fehler beim Dereferenzieren des Geräteobjekts in der Deloadroutine eines Treibers verhindert, dass der nächstniedrige Treiber entladen wird. Treiber, die das Dateiobjekt vor dem Entladungsvorgang schließen, müssen jedoch einen zusätzlichen Verweis auf das Geräteobjekt entfernen, bevor das Dateiobjekt deferenciert wird. Andernfalls kann die Deferencierung des Dateiobjekts zu einem vorzeitigen Löschen des Geräteobjekts führen.

Um einen Zeiger auf den Treiber der höchsten Ebene im Dateisystemtreiberstapel zu erhalten, muss ein Treiber sicherstellen, dass das Dateisystem eingebunden ist. andernfalls durchläuft diese Routine den Speichergerätestapel. Um sicherzustellen, dass das Dateisystem auf dem Speichergerät eingebunden ist, muss der Treiber im DesiredAccess-Parameter eine geeignete Zugriffsmaske angeben, z. B. FILE_READ_DATA oder FILE_WRITE_ATTRIBUTES. Wenn Sie FILE_READ_ATTRIBUTES angeben, wird das Dateisystem nicht eingebunden.

Nachdem sich ein höherstufiger Treiber durch erfolgreichen Aufruf dieser Routine über einen anderen Treiber verkettet hat, muss der Treiber der höheren Ebene das Feld StackSize in seinem Geräteobjekt auf das des Geräteobjekts des nächstniedrigen Treibers plus eins festlegen.

Aufrufer von IoGetDeviceObjectPointer müssen unter IRQL = PASSIVE_LEVEL ausgeführt werden.

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), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)