ScsiPortWmiSetInstanceName, fonction (scsiwmi.h)
La routine ScsiPortWmiSetInstanceName met à jour la structure WNODE_ALL_DATA dans le contexte de requête pour spécifier la position et la longueur d’un nom d’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 d’un SRB WMI.
[in] InstanceIndex
Contient un index qui indique l’instance pour laquelle la position et la longueur du nom de l’instance doivent être spécifiées.
[in] InstanceNameLength
Spécifie la taille en octets du nom de l’instance.
[out] BufferAvail
Doit contenir, en entrée, le nombre d’octets d’espace tampon dans la structure WNODE_ALL_DATA qui peut être utilisée pour décrire les noms et les données d’instance. En retour, ce membre contient le nombre d’octets d’espace 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 appeler ScsiPortWmiSetInstanceCount d’abord, mais après ScsiPortWmiSetInstanceCount a été appelé, il n’importe pas dans quel ordre le minidriver appelle ScsiPortWmiSetData et ScsiPortWmiSetInstanceName. Lorsque vous appelez ScsiPortWmiSetData ou ScsiPortWmiSetInstanceName, la valeur passée à la routine dans son paramètre BufferAvail doit être identique à la valeur retournée dans le paramètre BufferAvail par la routine WMI du port SCSI. Par exemple, supposons que le minidriver appelle ScsiPortWmiSetInstanceCount en premier, 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 une valeur de 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 d’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 l’ajout des données descriptives pour l’instance spécifiée par InstanceIndex. Lors du retour, ce membre contiendra la taille de l’intégralité du WNODE, y compris les données de la nouvelle instance.
Valeur de retour
La routine ScsiPortWmiSetInstanceCount retourne un pointeur vers la mémoire tampon où l’appelant peut stocker le nom de l’instance spécifiée dans InstanceIndex. Si ScsiPortWmiSetInstanceCount ne peut pas allouer suffisamment de mémoire pour le nom de l’instance, ou si le WNODE contenu dans le contexte de 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êtes SCSI Windows Management Instrumentation (WMI). La structure de contexte de requête contient à son tour l’une des WMI WNODE_XXX Structures 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. Cela est dû au fait que ScsiPortWmiSetInstanceName pouvez réserver une zone de nom d’instance pour toutes les instances associées à un bloc de données WMI. Contrairement à la structure WNODE_SINGLE_INSTANCE qui contient des informations sur une seule instance, la structure WNODE_ALL_DATA contient un tableau de pointeurs vers des zones tampons pour différentes instances, et ScsiPortWmiSetInstanceCount initialise ce tableau afin que chaque mémoire tampon de données d’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 l’état SRB final 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’une trame de pile qui ne dépasse pas l’étendue.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Bureau |
| d’en-tête | scsiwmi.h (include Miniport.h, Scsi.h) |