IOCTL_ATA_PASS_THROUGH IOCTL (ntddscsi.h)
Permet à une application d’envoyer presque n’importe quelle commande ATA à un appareil cible, avec les restrictions suivantes :
- S’il existe un pilote de classe pour le type d’appareil cible, l’application doit envoyer la demande au pilote de classe. Ainsi, une application peut envoyer cette requête directement au pilote de port système pour une unité logique cible (LU) uniquement s’il n’existe aucun pilote de classe pour le type d’appareil connecté à cette lu. Le pilote de port système ne case activée pas pour déterminer si un périphérique a été revendiqué par un pilote de classe avant de traiter une demande directe. Par conséquent, si une application contourne un pilote de classe qui a revendiqué un appareil et envoie une demande directe pour ce périphérique directement au pilote de port, un conflit de contrôle de l’appareil peut se produire entre le pilote de classe et l’application.
- Cette requête ne peut pas être utilisée si la commande nécessite que le pilote sous-jacent accède directement à la mémoire. Si la commande de l’appelant peut nécessiter un accès direct à la mémoire, utilisez IOCTL_ATA_PASS_THROUGH_DIRECT à la place.
- Les applications ne doivent pas tenter d’envoyer une demande directe de manière asynchrone. Toutes les demandes directes doivent être synchrones.
- Les applications ne nécessitent pas de privilèges administratifs pour envoyer une demande directe à un appareil, mais elles doivent disposer d’un accès en lecture/écriture à l’appareil.
Code principal
Mémoire tampon d'entrée
La mémoire tampon sur Irp-AssociatedIrp.SystemBuffer> doit contenir une structure ATA_PASS_THROUGH_EX, qui inclut un ensemble de registres d’entrée de fichier de tâches qui indiquent le type de commande à exécuter et ses paramètres. L’appelant doit initialiser tous les membres de cette structure à l’exception de PathId, TargetId et Lun, que le pilote de port remplit. Pour une commande data-out, le membre DataBufferOffset de la structure doit pointer vers une mémoire tampon alignée sur le cache contenant les données à écrire.
Longueur de la mémoire tampon d’entrée
Parameters.DeviceIoControl.InputBufferLength indique la taille en octets de la mémoire tampon sur Irp->AssociatedIrp.SystemBuffer. Si la commande ATA incorporée est une opération d’écriture, la taille de la mémoire tampon d’entrée doit être la somme de sizeof(ATA_PASS_THROUGH_EX) et la valeur dans le membre DataTransferLength de ATA_PASS_THROUGH_EX. L’exemple de pseudocode suivant montre comment calculer la taille de la mémoire tampon :ULONG buffsize; // size of the buffer
ATA_PASS_THROUGH_EX hdr;
hdr.DataTransferLength = size in bytes of the data transfer
buffsize = sizeof (ATA_PASS_THROUGH_EX) + hdr.DataTransferLength
Si la commande ATA incorporée est une opération de lecture ou une opération de contrôle d’appareil qui n’implique pas de transfert de données, InputBufferLength doit être égal à sizeof (ATA_PASS_THROUGH_EX).
Dans les deux cas, si InputBufferLength est inférieur à sizeof (ATA_PASS_THROUGH_EX), le pilote de port échoue à la requête d’E/S et retourne une erreur.
Mémoire tampon de sortie
Le pilote de port met en forme les données de retour à l’aide d’une structure ATA_PASS_THROUGH_EX et stocke les données dans la mémoire tampon sur Irp-AssociatedIrp.SystemBuffer>.
Le pilote de port remplit le membre CurrentTaskFile avec les valeurs présentes dans les registres de sortie de l’appareil à l’achèvement de la commande ATA incorporée. Si la commande était un transfert de données, le pilote de port stocke les données transférées dans une mémoire tampon alignée sur le cache qui se trouve à un décalage des octets DataBufferOffset par rapport au début de la structure. L’application est responsable de l’interprétation du contenu des registres de sortie pour déterminer les erreurs, le cas échéant, qui ont été retournées par l’appareil.
Longueur de la mémoire tampon de sortie
Le pilote de port met à jour le membre DataTransferLength de ATA_PASS_THROUGH_EX pour indiquer la quantité de données effectivement transférées à partir de l’appareil. Si la commande ATA incorporée est une opération d’écriture ou une opération de contrôle d’appareil qui ne transfère pas de données, OutputBufferLength est égal à sizeof(ATA_PASS_THROUGH_EX). Si la commande ATA incorporée est une opération de lecture, OutputBufferLength est égal à sizeof(ATA_PASS_THROUGH_EX) + DataTransferLength.
Bloc d’état
Le membre Information est défini sur le nombre d’octets retournés dans la mémoire tampon de sortie sur Irp-AssociatedIrp.SystemBuffer>. Le membre Status est défini sur STATUS_SUCCESS ou éventuellement sur STATUS_BUFFER_TOO_SMALL ou STATUS_INVALID_PARAMETER si la valeur d’entrée Status dans ATA_PASS_THROUGH_EX est incorrectement définie.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows Server 2003. |
| En-tête | ntddscsi.h (inclure Ntddscsi.h) |