PcwAddInstance, fonction (wdm.h)
La PcwAddInstance fonction ajoute le instance spécifié du compteur à la mémoire tampon du consommateur. La plupart des développeurs utilisent une fonction AddXxx générée par CTRPP au lieu d’appeler cette fonction directement. Pour plus d’informations, voir Remarques ci-dessous.
Syntaxe
NTSTATUS PcwAddInstance(
[in] PPCW_BUFFER Buffer,
[in] PCUNICODE_STRING Name,
[in] ULONG Id,
[in] ULONG Count,
[in] PPCW_DATA Data
);
Paramètres
[in] Buffer
Handle à la mémoire tampon gérée par le système à laquelle les instance du compteur seront ajoutés. Lorsque la mémoire tampon provient d’une PcwCallbackEnumerateInstances notification, PcwAddInstance n’enregistre que le nom et l’ID du instance. Lorsque la mémoire tampon provient d’une PcwCallbackCollectData notification, PcwAddInstance enregistre le nom, l’ID et les données (valeurs de compteur) du instance.
[in] Name
Pointeur vers la chaîne Unicode qui contient le nom du compteur instance. Cette valeur ne doit pas être NULL.
Les valeurs d’instance Name DOIVENT être stables dans le temps (la même instance logique doit utiliser la même Name valeur pour tous les appels du rappel) et doivent être uniques. Si le compteur est inscrit en tant que instance unique, le instance Name doit être vide (longueur 0). Si le compteur inscrit en tant que multi-instance, le instance Name ne doit pas être vide. La correspondance de nom d’instance ne respecte pas la casse. Les valeurs ne doivent donc Name pas différer uniquement selon la casse.
[in] Id
Valeur numérique qui spécifie l’identificateur Id associé au compteur instance.
Les valeurs d’instance Id DOIVENT être stables au fil du temps (la même instance doit utiliser la même Id valeur pour tous les appels du rappel), doivent être uniques (par exemple, n’utilisez pas 0 pour toutes les instances) et doivent être inférieures à 0xFFFFFFFE (n’utilisez PCW_ANY_INSTANCE_ID aucune instance). Dans la mesure du possible, le instance Id doit être significatif (par exemple, un contre-ensemble de processus peut utiliser un PID comme Id) au lieu d’arbitraire (par exemple, un numéro de séquence).
[in] Count
Nombre de descripteurs fournis dans le Data paramètre.
[in] Data
Tableau de descripteurs pour les blocs de données du fournisseur qui contiennent les valeurs de compteur de cette instance.
Valeur retournée
PcwAddInstance retourne l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
STATUS_SUCCESS |
Le instance a été correctement ajouté à la mémoire tampon. |
STATUS_INVALID_BUFFER_SIZE |
L’un des blocs de données du fournisseur est trop petit. Par exemple, supposons que lors de l’appel à PcwRegister, le fournisseur spécifie que le compteur X se trouve à un décalage de 100 du premier bloc de données de taille 4 octets. Si l’appel à PcwAddInstance spécifie que le premier bloc de données est de 50 octets, cette erreur status est retournée. |
Remarques
La PcwAddInstance fonction doit être appelée par la routine PCW_CALLBACK définie par le fournisseur lorsque le type de notification est PcwCallbackEnumerateInstances ou PcwCallbackCollectData. Le Buffer à utiliser provient du Info paramètre de la PCW_CALLBACK routine, par exemple Info->EnumerateInstances.Buffer ou Info->CollectData.Buffer.
Lorsqu’une PcwCallbackEnumerateInstances notification est appelée, PcwAddInstance ajoute les Name valeurs et Id à la mémoire tampon. En cas d’appel pour une PcwCallbackCollectData notification, PcwAddInstance ajoute les Namevaleurs de données de compteur , Idet à la mémoire tampon.
Fonction Add*** générée par CTRPP
La plupart des développeurs n’ont pas besoin d’appeler PcwAddInstance directement. Au lieu de cela, ils compilent un manifeste avec l’outil CTRPP et utilisent la fonction Add*** à partir de l’en-tête généré par CTRPP. La fonction générée se présente comme suit :
EXTERN_C __inline NTSTATUS
AddMyCounterset(
__in PPCW_BUFFER Buffer,
__in PCUNICODE_STRING Name,
__in ULONG Id,
__in_opt const MY_COUNTER_DATA *MyCounterData
)
{
PCW_DATA Data[1];
PAGED_CODE();
Data[0].Data = MyCounterData;
Data[0].Size = sizeof(MY_COUNTER_DATA);
return PcwAddInstance(Buffer,
Name,
Id,
1,
Data);
}
La fonction Add générée par CTRPP sera nommée PréfixeAddCounterset. Le préfixe est généralement vide, mais peut être présent si le -prefix paramètre a été utilisé sur la ligne de commande CTRPP. Counterset est le nom du compteur, comme spécifié dans le manifeste. La fonction aura des paramètres de données basés sur les structures définies dans le manifeste. La fonction enveloppe les blocs de données fournis par l’utilisateur dans un tableau de PCW_DATA structures, puis appelle PcwAddInstance.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible dans Windows 7 et versions ultérieures de Windows. |
| Plateforme cible | Universal |
| En-tête | wdm.h (inclure Wdm.h, Ntddk.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |