Funzione IoAttachDevice (wdm.h)

Articolo
03/08/2023

La routine IoAttachDevice collega l'oggetto dispositivo del chiamante a un oggetto dispositivo di destinazione denominato, in modo che le richieste di I/O associate al dispositivo di destinazione vengano indirizzate prima al chiamante.

Sintassi

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

Parametri

[in] SourceDevice

Puntatore all'oggetto dispositivo creato dal chiamante.

[in] TargetDevice

Puntatore a un buffer contenente il nome dell'oggetto dispositivo a cui deve essere collegato sourceDevice specificato.

[out] AttachedDevice

Puntatore all'archiviazione allocata del chiamante per un puntatore. In caso contrario, contiene un puntatore all'oggetto dispositivo di destinazione se l'allegato ha esito positivo.

Valore restituito

IoAttachDevice può restituire uno dei valori NTSTATUS seguenti:

Commenti

IoAttachDevice stabilisce il livello tra i driver in modo che gli stessi IRP possano essere inviati a ogni driver nella catena.

Questa routine viene usata dai driver intermedi durante l'inizializzazione. Consente a tale driver di collegare il proprio oggetto dispositivo a un altro dispositivo in modo che tutte le richieste effettuate al dispositivo originale vengano fornite prima al driver intermedio.

Il chiamante può essere stratinato solo nella parte superiore di una catena esistente di driver a livelli. IoAttachDevice cerca l'oggetto dispositivo più alto a livello su TargetDevice e collega a tale oggetto (che può essere TargetDevice). Pertanto, questa routine non deve essere chiamata se un driver che deve essere di livello superiore è già stato livelliato sul dispositivo di destinazione.

Si noti che per i driver e i driver del file system nello stack di archiviazione, IoAttachDevice apre il dispositivo di destinazione con FILE_READ_ATTRIBUTES e quindi chiama IoGetRelatedDeviceObject. Ciò non causa l'montaggio di un file system. Pertanto, una chiamata riuscita a IoAttachDevice restituisce l'oggetto dispositivo del driver di archiviazione, non quello del driver del file system.

Questa routine imposta il valore AlignmentRequirement in SourceDevice sul valore nell'oggetto dispositivo inferiore successivo e imposta stackSize sul valore nell'oggetto inferiore successivo più uno.

Avviso

AttachedDevice deve puntare a una posizione di memoria globale, ad esempio l'estensione del dispositivo del driver. IoAttachDevice apre l'oggetto file per il dispositivo di destinazione, aggiorna AttachedDevice, esegue il collegamento e quindi chiude l'oggetto file. Pertanto, il dispositivo di origine riceve la IRP_MJ_CLEANUP e IRP_MJ_CLOSE richieste per l'oggetto file prima che IoAttachDevice restituisca. Il driver deve inoltrare queste richieste al dispositivo di destinazione e AttachedDevice deve essere una posizione di memoria accessibile alle routine DispatchCleanup e DispatchClose del driver.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrqlIoPassive1(wdm)