IoAttachDeviceToDeviceStackSafe, fonction (ntddk.h)
La routine IoAttachDeviceToDeviceStackSafe attache l’objet d’appareil de l’appelant à l’objet d’appareil le plus haut dans une pile de pilotes.
Syntaxe
NTSTATUS IoAttachDeviceToDeviceStackSafe(
[in] PDEVICE_OBJECT SourceDevice,
[in] PDEVICE_OBJECT TargetDevice,
[out] PDEVICE_OBJECT *AttachedToDeviceObject
);
Paramètres
[in] SourceDevice
Pointeur vers un objet d’appareil créé par l’appelant.
[in] TargetDevice
Pointeur vers l’objet d’appareil dans la pile à laquelle l’objet SourceDevice doit être attaché.
[out] AttachedToDeviceObject
Lors de l’entrée, ce paramètre spécifie l’adresse de SourceDevice->DeviceExtension->AttachedToDeviceObject, qui doit contenir un pointeur NULL. En sortie, ce paramètre reçoit un pointeur vers l’objet d’appareil auquel l'SourceDevice a été attaché.
Valeur de retour
IoAttachDeviceToDeviceStackSafe retourne STATUS_SUCCESS si SourceDevice est correctement attaché au-dessus du TargetDevice; sinon, elle retourne STATUS_NO_SUCH_DEVICE.
Remarques
Comme IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe établit une couche entre les pilotes afin que les mêmes IRPs soient envoyés à chaque pilote de la pile. Toutefois, contrairement à IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe a un paramètre supplémentaire, AttachedToDeviceObject, que le pilote de filtre utilise pour passer l’adresse du champ AttachedToDeviceObject de l’objet SourceDevice'objet AttachedToDeviceObject. IoAttachDeviceToDeviceStackSafe met à jour ce champ tout en maintenant le verrou de base de données système d’E/S. Étant donné qu’il contient ce verrou, IoAttachDeviceToDeviceStackSafe évite une condition de concurrence qui pourrait autrement se produire si l’objet SourceDevice a reçu un IRP avant la mise à jour de son champ AttachedToDeviceObject.
Un pilote de filtre de système de fichiers appelle IoAttachDeviceToDeviceStackSafe pour attacher son propre objet d’appareil de filtre (SourceDevice) au-dessus d’un objet d’appareil (TargetDevice) appartenant à un système de fichiers ou à un autre pilote de filtre. Les demandes d’E/S suivantes envoyées à AttachedToDeviceObject sont reçues en premier par le pilote de filtre, qui les traite et les transfère au pilote suivant dans la pile en appelant IoCallDriver.
Si l’objet d’appareil spécifié par TargetDevice se trouve actuellement en haut de la pile des pilotes, le sourceDevice est attaché directement au TargetDevice. Dans ce cas, targetDevice et le pointeur AttachedToDeviceObject retourné sont égaux.
Si un ou plusieurs objets d’appareil de filtre sont déjà attachés au-dessus du TargetDevice dans la pile des pilotes, IoAttachDeviceToDeviceStackSafe attache l'SourceDevice à l’objet d’appareil de filtre le plus haut. Un pointeur vers ce dernier est retourné dans AttachedToDeviceObject.
À l’heure actuelle immédiatement après qu’elle est attachée au haut de la pile, la SourceDevice occupe le haut de la pile des pilotes. Notez toutefois que cela ne signifie pas nécessairement que le SourceDevice reste en haut de la pile des pilotes. D’autres filtres peuvent attacher leurs propres objets d’appareil de filtre au-dessus du SourceDevice dans la pile.
IoAttachDeviceToDeviceStackSafe définit le membre AlignmentRequirement de l’objet d’appareil pointé par SourceDevice à la valeur de l’objet d’appareil inférieur suivant et définit la StackSize dans SourceDevice à la valeur de l’objet inférieur suivant plus un.