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