IOCTL_ATA_PASS_THROUGH IOCTL (ntdddscsi.h)
Permet à une application d’envoyer presque n’importe quelle commande ATA à un appareil cible, avec les restrictions suivantes :
- Si un pilote de classe pour le type cible d’appareil existe, l’application doit envoyer la demande au pilote de classe. Par conséquent, 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 vérifie pas 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 pour le 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 requête directe de manière asynchrone. Toutes les demandes directes doivent être synchrones.
- Les applications ne nécessitent pas de privilèges d’administration pour envoyer une demande directe à un appareil, mais elles doivent avoir un accès en lecture/écriture à l’appareil.
Code principal
Mémoire tampon d’entrée
La mémoire tampon à Irp->AssociatedIrp.SystemBuffer doit contenir une structure ATA_PASS_THROUGH_EX, qui inclut un ensemble de registres d’entrée de fichier de tâche qui indiquent le type de commande à effectuer et ses paramètres. L’appelant doit initialiser tous les membres de cette structure, à l’exception de PathId, TargetIdet Lun, dans lequel le pilote de port se renseigne. Pour une commande data-out, le DataBufferOffset membre 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 à 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 taille de(ATA_PASS_THROUGH_EX) et de 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 le transfert de données, InputBufferLength doit être égal à taille de (ATA_PASS_THROUGH_EX).
Dans les deux cas, si inputBufferLength est inférieur à taille de (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 à 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 située à un décalage de DataBufferOffset octets à partir du début de la structure. L’application est chargée d’interpréter le contenu des registres de sortie pour déterminer quelles erreurs, le cas échéant, ont été retournées par l’appareil.
Longueur de la mémoire tampon de sortie
Le pilote de port met à jour le DataTransferLength membre de ATA_PASS_THROUGH_EX pour indiquer la quantité de données réellement 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 égale à taille de(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 d’informations est défini sur le nombre d’octets retournés dans la mémoire tampon de sortie à >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 Status d’entrée dans ATA_PASS_THROUGH_EX est incorrectement définie.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows Server 2003. |
| d’en-tête | ntddscsi.h (include Ntddscsi.h) |