IoAttachDevice-Funktion (wdm.h)

Artikel
02/27/2024

Die IoAttachDevice-Routine fügt das Geräteobjekt des Aufrufers an ein benanntes Zielgerätobjekt an, sodass E/A-Anforderungen, die für das Zielgerät gebunden sind, zuerst an den Aufrufer weitergeleitet werden.

Syntax

NTSTATUS IoAttachDevice(
  [in]  PDEVICE_OBJECT  SourceDevice,
  [in]  PUNICODE_STRING TargetDevice,
  [out] PDEVICE_OBJECT  *AttachedDevice
);

Parameter

[in] SourceDevice

Zeiger auf das vom Aufrufer erstellte Geräteobjekt.

[in] TargetDevice

Zeiger auf einen Puffer, der den Namen des Geräteobjekts enthält, an das das angegebene SourceDevice angefügt werden soll.

[out] AttachedDevice

Zeiger auf den vom Aufrufer zugewiesenen Speicher für einen Zeiger. Enthält bei der Rückgabe einen Zeiger auf das Zielgerätobjekt, wenn die Anlage erfolgreich ist.

Rückgabewert

IoAttachDevice kann einen der folgenden NTSTATUS-Werte zurückgeben:

Hinweise

IoAttachDevice richtet layering zwischen Treibern ein, sodass dieselben IRPs an jeden Treiber in der Kette gesendet werden können.

Diese Routine wird von Zwischentreibern während der Initialisierung verwendet. Es ermöglicht einem solchen Treiber, sein eigenes Geräteobjekt so an ein anderes Gerät anzufügen, dass alle Anforderungen, die an das ursprüngliche Gerät gestellt werden, zuerst an den Zwischentreiber gesendet werden.

Der Aufrufer kann nur am Anfang einer vorhandenen Kette von mehrschichtigen Treibern mehrschichtige Ebenen enthalten. IoAttachDevice sucht nach dem höchsten Geräteobjekt, das über TargetDevice verteilt ist, und fügt an dieses Objekt an (bei dem es sich um das TargetDevice handeln kann). Daher darf diese Routine nicht aufgerufen werden, wenn sich ein Treiber, der höher sein muss, bereits über das Zielgerät verteilt hat.

Beachten Sie, dass IoAttachDevice für Dateisystemtreiber und Treiber im Speicherstapel das Zielgerät mit FILE_READ_ATTRIBUTES öffnet und dann IoGetRelatedDeviceObject aufruft. Dies führt nicht dazu, dass ein Dateisystem eingebunden wird. Daher gibt ein erfolgreicher Aufruf von IoAttachDevice das Geräteobjekt des Speichertreibers zurück, nicht das des Dateisystemtreibers.

Diese Routine legt das AlignmentRequirement in SourceDevice auf den Wert im nächstniedrigen Geräteobjekt fest und legt stackSize auf den Wert im nächstniedrigen Objekt plus 1 fest.

Warnung

AttachedDevice muss auf einen globalen Speicherort verweisen, z. B. die Geräteerweiterung des Treibers. IoAttachDevice öffnet das Dateiobjekt für das Zielgerät, aktualisiert AttachedDevice, führt das Anfügen aus und schließt dann das Dateiobjekt. Daher empfängt das Quellgerät die IRP_MJ_CLEANUP und IRP_MJ_CLOSE Anforderungen für das Dateiobjekt, bevor IoAttachDevice zurückgibt. Der Treiber muss diese Anforderungen an das Zielgerät weiterleiten, und AttachedDevice muss ein Speicherspeicherort sein, der für die DispatchCleanup - und DispatchClose-Routinen des Treibers zugänglich ist.

Anforderungen

Anforderung	Wert
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), IrqlIoPassive1(wdm)