PcwCreateInstance, fonction (wdm.h)

La PcwCreateInstance fonction crée un instance de compteur. La plupart des développeurs utilisent une fonction CreateXxx générée par CTRPP au lieu d’appeler cette fonction directement.

Syntaxe

NTSTATUS PcwCreateInstance(
  [out] PPCW_INSTANCE     *Instance,
  [in]  PPCW_REGISTRATION Registration,
  [in]  PCUNICODE_STRING  Name,
  [in]  ULONG             Count,
  [in]  PPCW_DATA         Data
);

Paramètres

[out] Instance

Pointeur pour recevoir le instance nouvellement créé. Le instance doit être fermé à l’aide de PcwCloseInstance.

[in] Registration

Pointeur vers l’inscription de l’ensemble de compteurs qui possède ce instance. L’inscription est créée à l’aide de PcwRegister.

[in] Name

Pointeur vers la chaîne Unicode qui contient le nom du instance du compteur. 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] 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. Les blocs de données référencés par les descripteurs sont accessibles à tout moment et doivent rester valides jusqu’à ce que le instance soit fermé par PcwCloseInstance ou PcwUnregister.

Valeur retournée

PcwCreateInstance retourne l’une des valeurs suivantes :

Remarques

Les fournisseurs de contre-ensembles peuvent fournir des informations au consommateur par le biais de deux systèmes différents :

• Le fournisseur peut fournir une PCW_CALLBACK fonction qui sera appelée par la bibliothèque de compteurs de performances en fonction des besoins pour collecter des données. Pour plus d’informations sur ce système, reportez-vous à la documentation pour PCW_CALLBACK.
• Le fournisseur peut utiliser PcwCreateInstance et PcwCloseInstance pour gérer une liste d’instances disponibles et les données de compteur correspondantes. Ce système est simple à implémenter, mais sa flexibilité est limitée.

Avant que le fournisseur utilise cette fonction, le fournisseur doit appeler la PcwRegister fonction pour créer une inscription.

Lorsqu’une nouvelle instance arrive (par exemple, lorsqu’un appareil est branché), le fournisseur doit allouer et initialiser un bloc de données pour le instance, appeler PcwCreateInstance avec le nom et le bloc de données pour le instance, puis conserver les valeurs du bloc de données mises à jour avec les valeurs de compteur pour le instance. Lorsque le instance devient non valide (par exemple, lorsqu’un appareil est débranché), le fournisseur doit appelerPcwCloseInstance, puis supprimer le bloc de données.

Le fournisseur doit conserver les blocs de données (généralement dans un pool paginé ou non paginé) contenant les valeurs de compteur actuelles pour chaque instance.

PcwCreateInstanceaffecte automatiquement un ID unique pour le instance. Pour fournir des valeurs spécifiques pour l’ID instance, implémentez une PCW_CALLBACK fonction au lieu d’utiliser PcwCreateInstance.

Utilisez la fonction PcwCloseInstance pour fermer le instance.

Fonction CreateXxx générée par CTRPP

La plupart des développeurs n’ont pas besoin d’appeler PcwCreateInstance directement. Au lieu de cela, ils compilent un manifeste avec l’outil CTRPP et utilisent la fonction CreateXxx à 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
CreateMyCounterset(
    __deref_out PPCW_INSTANCE *Instance,
    __in PCUNICODE_STRING Name,
    __in const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwCreateInstance(Instance,
                             MyCounterset,
                             Name,
                             1,
                             Data);
}

La fonction Create générée par CTRPP sera nommée PréfixeCreateCounterset. 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 PcwCreateInstance. Notez que la fonction fait référence à une variable Counterset (MyCounterset dans l’exemple), qui est une variable globale qui contient le handle d’inscription de compteur initialisé par la fonction RegisterXxx générée par CTRPP.

Configuration requise

Voir aussi

PcwCloseInstance, fonction

PcwRegister, fonction