Exécution de la gestion des ensembles de données du pilote de stockage

À compter de Windows 7, les pilotes peuvent effectuer des actions de gestion sur le jeu de données d’un appareil. La liste des actions de gestion des ensembles de données (DSM) qui peuvent être effectuées sur un appareil de stockage est définie par Microsoft.

Utilisation de IOCTL_STORAGE_MANAGE_DATA_SET_ATTRIBUTES

Une constante DEVICE_DSM_ACTION spécifie l’action. Cette constante est transmise dans le membre Action de la structure DEVICE_DSM_INPUT contenue dans la mémoire tampon système d’une demande de IOCTL_STORAGE_MANAGE_DATA_SET_ATTRIBUTES . Si l’action nécessite des paramètres supplémentaires, un bloc de paramètres suit immédiatement la structure DEVICE_DSM_INPUT, et ParameterBlockOffset spécifie le décalage à partir du début de la structure DEVICE_DSM_INPUT à laquelle le bloc de paramètres démarre. Les plages de jeux de données, le cas échéant, suivent immédiatement le bloc de paramètres, et DataSetRangesOffset spécifie le décalage à partir du début de la structure de DEVICE_DSM_INPUT à laquelle commence la ou les plages. La structure de la mémoire tampon système est illustrée dans le diagramme suivant.

Si l’action de gestion retourne une sortie, un pointeur vers une structure de DEVICE_DSM_OUTPUT est passé dans outputBuffer d’IOCTL. Si l’action retourne une sortie supplémentaire spécifique à l’action, un bloc de sortie suit immédiatement la structure DEVICE_DSM_OUTPUT et OutputBlockOffset spécifie le décalage à partir du début de la structure DEVICE_DSM_OUTPUT à laquelle le bloc de paramètres démarre. La structure de la mémoire tampon de sortie est illustrée dans le diagramme suivant.

Flux de processus d’une action DSM

Le flux de processus d’une action DSM est décrit ci-dessous, où Sender est le demandeur d’action et Handler traite l’action demandée. Notez qu’il peut y avoir plusieurs gestionnaires dans la pile.

1. L’expéditeur initialise le DSM et l’envoie au premier gestionnaire de la pile en procédant comme suit :

   • Allouez et initialisez une structure de DEVICE_DSM_DEFINITION avec la définition associée à l’action.
   • Appelez DeviceDsmGetInputLength pour déterminer la taille requise pour la mémoire tampon d’entrée de l’action, puis allouer de la mémoire pour cette mémoire tampon.
   • Appelez DeviceDsmInitializeInput pour initialiser la structure DSM_DEVICE_INPUT et, si l’action a des paramètres, le bloc de paramètres. Le format de bloc de paramètre dépend de l’action. Pour plus d’informations, consultez descriptions DEVICE_DSM_ACTION .
   • Si l’action comporte des plages, appelez DeviceDsmAddDataSetRange pour chaque plage afin d’ajouter DEVICE_DSM_RANGE structure(s) à la mémoire tampon d’entrée.
   • Si le DSM a une sortie, appelez DeviceDsmGetOutputLength pour déterminer la taille requise pour la mémoire tampon de sortie de l’action, puis allouer de la mémoire pour cette mémoire tampon.
   • Envoyez une IOCTL_STORAGE_MANAGE_DATA_SET_ATTRIBUTES demande, en transmettant les données d’entrée initialisées dans la mémoire tampon système de IOCTL, ainsi que la mémoire tampon de sortie allouée, le cas échéant.

2. Le gestionnaire gère la requête IOCTL DSM de l’une des trois manières suivantes :

   1. Gérez la demande et retournez avec la sortie, le cas échéant.
   2. Gérez la requête et transférez-la au pilote inférieur suivant dans la pile.
   3. Transférez la demande au pilote inférieur suivant de la pile sans gérer le DSM.

   Notes

   Que le pilote gère ou non le DSM, il peut transférer la demande en toute sécurité uniquement si le bit le plus significatif (DeviceDsmActionFlag_NonDestructive) de DEVICE_DSM_ACTION est défini. Si DeviceDsmActionFlag_NonDestructiven’est pas défini, le pilote doit plutôt revenir avec une erreur.

   Si le gestionnaire gère le DSM, il effectue les étapes suivantes :

   • Validez l’entrée en appelant DeviceDsmValidateInput.
   • Si l’entrée est valide, le gestionnaire extrait l’entrée pour obtenir l’action. Si l’action a un bloc de paramètres, le gestionnaire appelle DeviceDsmParameterBlock pour obtenir le bloc de paramètres. Si l’action contient des données de plage, le gestionnaire appelle DeviceDsmDataSetRanges pour obtenir un pointeur vers le bloc de plages de jeux de données, puis effectue le traitement normal sur le bloc. Ce bloc se trouve dans DataSetRangesOffset et se compose d’une ou plusieurs entrées contiguës mises en forme en tant que structures DEVICE_DSM_RANGE . La longueur, en octets, des plages de jeux de données est définie dans le membre DataSetRangesLength de DEVICE_DSM_INPUT.
   • Si l’action nécessite une sortie, le gestionnaire appelle DeviceDsmValidateOutputLength pour valider la mémoire tampon de sortie fournie par l’expéditeur. S’il est valide, le gestionnaire initialise la partie DEVICE_DSM_OUTPUT de la mémoire tampon de sortie en appelant DeviceDsmInitializeOutput et remplit le bloc de sortie avec une sortie spécifique à l’action, le cas échéant. Le gestionnaire termine ensuite le IOCTL et retourne ou transfère le IOCTL au pilote suivant dans la pile.

3. Une fois le DSM géré et retourné à l’expéditeur, l’expéditeur valide la sortie, le cas échéant, en appelant DeviceDsmValidateOutput. Si la sortie est valide, Sender extrait le bloc de sortie, le cas échéant, en appelant DeviceDsmOutputBlock.

Pour plus d’informations sur chaque action DSM spécifique, consultez Description des actions DSM d’appareil.