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 requête 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, suivront immédiatement le bloc de paramètres, et DataSetRangesOffset spécifiera le décalage à partir du début de la structure DEVICE_DSM_INPUT où 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 la sortie, un pointeur vers une structure DEVICE_DSM_OUTPUT est transmis dans le OutputBuffer du 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 de DEVICE_DSM_OUTPUT au démarrage du bloc de paramètres. 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ù l’expéditeur est le demandeur d’actions et le gestionnaire 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 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ètres dépend de l’action. Pour plus d’informations, consultez DEVICE_DSM_ACTION Descriptions .
   • 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 allouez de la mémoire pour cette mémoire tampon.
   • Envoyez une requête IOCTL_STORAGE_MANAGE_DATA_SET_ATTRIBUTES , en passant les données d’entrée initialisées dans la mémoire tampon système du IOCTL, ainsi que la mémoire tampon de sortie allouée, le cas échéant.

2. Le gestionnaire gère la demande IOCTL DSM de trois façons :

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

   Remarque

   Indépendamment du fait que le pilote gère le DSM, il peut transférer la requête en toute sécurité uniquement si le bit le plus significatif de DEVICE_DSM_ACTION (DeviceDsmActionFlag_NonDestructive) est défini. Si DeviceDsmActionFlag_NonDestructiven’est pas défini, le pilote devrait plutôt renvoyer 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 comporte 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. Si elle 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 l'IOCTL et le retourne ou le transfère au pilote suivant dans la pile de drivers.

3. Une fois que le DSM est 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, l’expéditeur extrait le bloc de sortie, le cas échéant, en appelant DeviceDsmOutputBlock.

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