Fonction ScsiPortWmiSetInstanceName (scsiwmi.h)
La routine ScsiPortWmiSetInstanceName met à jour la structure WNODE_ALL_DATA dans le contexte de la demande pour spécifier la position et la longueur d’un nom de instance.
Syntaxe
PWCHAR ScsiPortWmiSetInstanceName(
[in] PSCSIWMI_REQUEST_CONTEXT RequestContext,
[in] ULONG InstanceIndex,
[in] ULONG InstanceNameLength,
[out] PULONG BufferAvail,
[in, out] PULONG SizeNeeded
);
Paramètres
[in] RequestContext
Pointeur vers une structure de type SCSIWMI_REQUEST_CONTEXT qui contient le contexte de requête pour un SRB WMI.
[in] InstanceIndex
Contient un index qui indique le instance pour lequel la position et la longueur du nom instance doivent être spécifiées.
[in] InstanceNameLength
Spécifie la taille en octets du nom instance.
[out] BufferAvail
Doit contenir, lors de l’entrée, le nombre d’octets d’espace tampon dans la structure WNODE_ALL_DATA qui peut être utilisé pour décrire les noms et les données instance. Au retour, ce membre contient le nombre d’octets d’espace de mémoire tampon qui restent.
Il existe trois routines WMI de port SCSI qui retournent une valeur pour la taille de mémoire tampon disponible dans leur paramètre BufferAvail :
ScsiPortWmiSetInstanceName
Le pilote miniport doit d’abord appeler ScsiPortWmiSetInstanceCount , mais une fois que ScsiPortWmiSetInstanceCount a été appelé, peu importe dans quel ordre le minidriver appelle ScsiPortWmiSetData et ScsiPortWmiSetInstanceName. Lors de l’appel de ScsiPortWmiSetData ou ScsiPortWmiSetInstanceName, la valeur transmise à la routine dans son paramètre BufferAvail doit être identique à la valeur retournée dans le paramètre BufferAvail par la dernière routine WMI du port SCSI. Par instance, supposons que le minidriver appelle d’abord ScsiPortWmiSetInstanceCount et que cette routine retourne une valeur de 1 000 dans son paramètre BufferAvail. Ensuite, le minidriver appelle ScsiPortWmiSetData qui retourne une valeur de 500 dans son paramètre BufferAvail . Enfin, le minidriver appelle ScsiPortWmiSetInstanceName qui retourne la valeur 200 dans son paramètre BufferAvail . La valeur initiale de 1 000 doit être passée à ScsiPortWmiSetData dans BufferAvail, et la valeur de 500 doit être passée à ScsiPortWmiSetInstanceName.
S’il n’y a pas suffisamment de mémoire disponible pour ajouter un nom instance de longueur InstanceNameLength, un zéro est retourné dans le membre BufferAvail.
[in, out] SizeNeeded
Indique, lors de l’entrée, le nombre d’octets nécessaires pour décrire le WNODE avant d’ajouter les données descriptives pour le instance spécifié par InstanceIndex. Au retour, ce membre contient la taille de l’ensemble du WNODE, y compris les données du nouveau instance.
Valeur retournée
La routine ScsiPortWmiSetInstanceCount retourne un pointeur vers la mémoire tampon où l’appelant peut stocker le nom du instance spécifié dans InstanceIndex. Si ScsiPortWmiSetInstanceCount ne peut pas allouer suffisamment de mémoire pour le nom instance, ou si le WNODE contenu dans le contexte de la requête n’est pas de type WNODE_ALL_DATA, ScsiPortWmiSetData retourne NULL.
Remarques
Le minidriver doit appeler ScsiPortWmiSetInstanceCount avant d’appeler ScsiPortWmiSetInstanceName.
Le paramètre RequestContext pointe vers une structure de contexte de requête, SCSIWMI_REQUEST_CONTEXT, qui contient des informations associées à un bloc de requête SCSI (SRB) WMI (Windows Management Instrumentation ). La structure de contexte de la demande, à son tour, contient l’une des structures de WNODE_XXX WMI utilisées par le système WMI pour transmettre des données entre les consommateurs de données en mode utilisateur et les fournisseurs de données en mode noyau, tels que les pilotes.
La routine ScsiPortWmiSetInstanceName nécessite que la structure WNODE définie dans le contexte de requête soit de type WNODE_ALL_DATA. En effet, ScsiPortWmiSetInstanceName peut réserver une zone de nom instance pour toutes les instances associées à un bloc de données WMI. Contrairement à la structure WNODE_SINGLE_INSTANCE qui contient des informations sur un seul instance, la structure WNODE_ALL_DATA contient un tableau de pointeurs vers des zones de mémoire tampon pour différentes instances, et ScsiPortWmiSetInstanceCount initialise ce tableau, afin que chaque mémoire tampon de données instance soit accessible individuellement.
La mémoire allouée pour le contexte de requête doit rester valide jusqu’à ce que le pilote miniport appelle ScsiPortWmiPostProcess, et ScsiPortWmiPostProcess retourne la status SRB finale et la taille de la mémoire tampon. Si le SRB peut être suspendu, la mémoire du contexte de requête doit être allouée à partir de l’extension SRB. Si le SRB ne peut pas être suspendu, la mémoire peut être allouée à partir d’un frame de pile qui ne sort pas de l’étendue.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Desktop (Expérience utilisateur) |
| En-tête | scsiwmi.h (inclure Miniport.h, Scsi.h) |