Fonction IoAttachDeviceToDeviceStackSafe (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. Lors de la sortie, ce paramètre reçoit un pointeur vers l’objet d’appareil auquel l’objet SourceDevice a été attaché.

Valeur retournée

IoAttachDeviceToDeviceStackSafe retourne STATUS_SUCCESS si SourceDevice est correctement attaché au-dessus du TargetDevice ; sinon, il retourne STATUS_NO_SUCH_DEVICE.

Remarques

Comme IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe établit la superposition 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 transmettre l’adresse du champ AttachedToDeviceObject de l’objet SourceDevice . IoAttachDeviceToDeviceStackSafe met à jour ce champ tout en tenant le verrou de base de données système d’E/S. Étant donné qu’il contient ce verrou, IoAttachDeviceToDeviceStackSafe évite une condition de course qui pourrait 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 de périphérique 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 de pilotes, l’objet 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 de TargetDevice dans la pile des pilotes, IoAttachDeviceToDeviceStackSafe attache sourceDevice à l’objet d’appareil de filtre supérieur. Un pointeur vers ce dernier est retourné dans AttachedToDeviceObject.

À l’heure actuelle, immédiatement après son attachement au haut de la pile, l’élément SourceDevice occupe le haut de la pile de pilotes. Notez toutefois que cela ne signifie pas nécessairement que SourceDevice reste en haut de la pile des pilotes. D’autres filtres peuvent attacher leurs propres objets d’appareil de filtre au-dessus de l’objet SourceDevice dans la pile.

IoAttachDeviceToDeviceStackSafe définit le membre AlignmentRequirement de l’objet d’appareil pointé par SourceDevice sur la valeur du correspondant dans l’objet d’appareil inférieur suivant et définit stackSize dans SourceDevice sur la valeur de l’objet suivant-inférieur-plus un.

Configuration requise

Voir aussi

IoAttachDeviceToDeviceStack

IoCallDriver