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
Zeigen Sie auf einen Puffer, der eine Unicode-Zeichenfolge enthält, die den Namen des Geräteobjekts darstellt.
[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
Zeigen Sie auf das Dateiobjekt, das das entsprechende Geräteobjekt auf Benutzermoduscode darstellt, wenn der Aufruf erfolgreich ist.
[out] DeviceObject
Zeigen Sie auf das Geräteobjekt, das das benannte logische, virtuelle oder physische Gerät darstellt, wenn der Aufruf erfolgreich ist.
Rückgabewert
IoGetDeviceObjectPointer gibt STATUS_SUCCESS zurück, wenn dies erfolgreich ist. Mögliche Fehlerrücklaufwerte sind die folgenden Statuscodes:
STATUS_OBJECT_TYPE_MISMATCH
STATUS_INVALID_PARAMETER
STATUS_PRIVILEGE_NOT_HELD
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_INVALID
Bemerkungen
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 verwendet werden , um ioAttachDeviceToDeviceToDeviceStack, IoCallDriver, und jede Routine, 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 das Dateiobjekt als Mittel zur indirekten Ableitung des Geräteobjekts ableiten. Dazu ruft der Treiber ObDereferenceObject aus seiner Unload-Routine auf und übergibt den von IoGetDeviceObjectPointerzurückgegebenen Dateiobjektzeiger. Fehler beim Ableiten des Geräteobjekts in der Unload-Routine eines Treibers verhindert, dass der nächste niedrigere Treiber entladen wird. Treiber, die das Dateiobjekt vor dem Entladen schließen, müssen jedoch einen zusätzlichen Verweis auf das Geräteobjekt ausführen, bevor das Dateiobjekt abgeleitet wird. Andernfalls kann das Ableiten 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 bereitgestellt wird. Wenn dies nicht der Fall ist, durchläuft diese Routine den Speichergerätestapel. Um sicherzustellen, dass das Dateisystem auf dem Speichergerät bereitgestellt wird, muss der Treiber im Parameter DesiredAccess eine entsprechende Zugriffsmaske angeben, z. B. FILE_READ_DATA oder FILE_WRITE_ATTRIBUTES. Wenn Sie FILE_READ_ATTRIBUTES angeben, wird das Dateisystem nicht bereitgestellt.
Nachdem sich jeder Treiber auf höherer Ebene durch erfolgreiches Aufrufen dieser Routine über einen anderen Treiber verkettet hat, muss der Treiber auf höherer Ebene das StackSize-Feld in seinem Geräteobjekt auf das des Geräteobjekts der nächsten niedrigeren Ebene plus eins festlegen.
Aufrufer von IoGetDeviceObjectPointer- müssen unter IRQL = PASSIVE_LEVEL ausgeführt werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Ab Windows 2000 verfügbar. |
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL |
| DDI-Complianceregeln | HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |