Funzione IoAttachDeviceToDeviceStackSafe (ntddk.h)
La routine IoAttachDeviceToDeviceStackSafe collega l'oggetto dispositivo del chiamante all'oggetto dispositivo più in alto in uno stack di driver.
Sintassi
NTSTATUS IoAttachDeviceToDeviceStackSafe(
[in] PDEVICE_OBJECT SourceDevice,
[in] PDEVICE_OBJECT TargetDevice,
[out] PDEVICE_OBJECT *AttachedToDeviceObject
);
Parametri
[in] SourceDevice
Puntatore a un oggetto dispositivo creato dal chiamante.
[in] TargetDevice
Puntatore all'oggetto dispositivo nello stack a cui deve essere collegato l'oggetto SourceDevice.
[out] AttachedToDeviceObject
In caso di input, questo parametro specifica l'indirizzo di SourceDevice->DeviceExtension->AttachedToDeviceObject, che deve contenere un puntatore NULL. In caso di output, questo parametro riceve un puntatore all'oggetto dispositivo a cui è stato collegato il SourceDevice.
Valore restituito
IoAttachDeviceToDeviceStackSafe restituisce STATUS_SUCCESS se SourceDevice è collegato correttamente sopra il TargetDevice; in caso contrario restituisce STATUS_NO_SUCH_DEVICE.
Osservazioni
Come IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe stabilisce il layering tra i driver in modo che gli stessi runtime di integrazione vengano inviati a ogni driver nello stack. Tuttavia, a differenza di IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe ha un parametro aggiuntivo, AttachedToDeviceObject, che il driver di filtro usa per passare l'indirizzo del campo AttachedToDeviceObject dell'oggetto SourceDevice. IoAttachDeviceToDeviceStackSafe aggiorna questo campo mantenendo il blocco del database di sistema I/O. Poiché contiene questo blocco, IoAttachDeviceToDeviceStackSafe evita una race condition che potrebbe verificarsi altrimenti se l'oggetto SourceDevice ha ricevuto un IRP prima dell'aggiornamento del campo AttachedToDeviceObject.
Un driver di filtro del file system chiama IoAttachDeviceToDeviceStackSafe per collegare il proprio oggetto dispositivo filtro (SourceDevice) sopra un oggetto dispositivo (TargetDevice) appartenente a un file system o a un altro driver di filtro. Le successive richieste di I/O inviate a AttachedToDeviceObject vengono ricevute prima dal driver di filtro, che li elabora e li inoltra al driver successivo nello stack chiamando IoCallDriver.
Se l'oggetto dispositivo specificato da TargetDevice si trova attualmente all'inizio dello stack di driver, il SourceDevice viene collegato direttamente al TargetDevice. In questo caso, TargetDevice e il AttachedToDeviceObject restituito puntatore sono uguali.
Se uno o più oggetti dispositivo filtro sono già collegati sopra il TargetDevice nello stack di driver, IoAttachDeviceToDeviceStackSafe collega il SourceDevice all'oggetto dispositivo con filtro superiore. Un puntatore a quest'ultimo viene restituito in AttachedToDeviceObject.
Al momento immediatamente dopo che è collegato alla parte superiore dello stack, il SourceDevice occupa la parte superiore dello stack di driver. Si noti, tuttavia, che questo non significa necessariamente che il SourceDevice rimarrà nella parte superiore dello stack di driver. Altri filtri possono collegare i propri oggetti dispositivo filtro sopra il SourceDevice nello stack.
IoAttachDeviceToDeviceStackSafe imposta il membro AlignmentRequirement dell'oggetto dispositivo a cui punta SourceDevice sul valore dell'oggetto corrispondente nell'oggetto dispositivo inferiore successivo e imposta il StackSize in SourceDevice al valore nell'oggetto più uno successivo.