Fonction de rappel PERFLIBREQUEST (perflib.h)

Article
08/25/2023

Les fournisseurs peuvent implémenter cette fonction pour recevoir une notification lorsque les consommateurs effectuent certaines actions, telles que l’ajout ou la suppression de compteurs d’une requête. PERFLIB appelle le rappel avant la fin de la demande du consommateur.

Le type PERFLIBREQUEST définit un pointeur vers cette fonction de rappel. La fonction ControlCallback est un espace réservé pour le nom de la fonction définie par l’application.

Syntaxe

PERFLIBREQUEST Perflibrequest;

ULONG Perflibrequest(
  [in] ULONG RequestCode,
  [in] PVOID Buffer,
  [in] ULONG BufferSize
)
{...}

Paramètres

[in] RequestCode

Le code de demande peut être l’une des valeurs suivantes.

Valeur	Signification
PERF_ADD_COUNTER	Le consommateur ajoute un compteur à la requête. PERFLIB appelle le rappel avec ce code de requête pour chaque compteur ajouté à la requête. Le paramètre Buffer contient une structure PERF_COUNTER_IDENTITY qui identifie le compteur ajouté. Les fournisseurs peuvent utiliser cette notification pour commencer à compter.
PERF_REMOVE_COUNTER	Le consommateur supprime un compteur de la requête. PERFLIB appelle le rappel avec ce code de requête pour chaque compteur supprimé de la requête. Le paramètre Buffer contient une structure PERF_COUNTER_IDENTITY qui identifie le compteur en cours de suppression. Les fournisseurs peuvent utiliser cette notification pour arrêter le comptage.
PERF_ENUM_INSTANCES	Le consommateur énumére les instances du jeu de compteurs. Le paramètre Buffer contient une chaîne Unicode terminée par null qui identifie le nom de l’ordinateur (ou son adresse IP) à partir duquel le consommateur énumère les instances.
PERF_COLLECT_START	Le consommateur commence à collecter des données de compteur. Le paramètre Buffer contient une chaîne Unicode terminée par null qui identifie le nom de l’ordinateur (ou son adresse IP) à partir duquel le consommateur collecte des données. Les fournisseurs peuvent utiliser cette notification si l’état des données brutes est critique (par exemple, les compteurs liés aux transactions où les mises à jour partielles ne sont pas autorisées). Cette notification permet au fournisseur de vider toutes les mises à jour en attente et de verrouiller les futures mises à jour avant le début de la collecte.
PERF_COLLECT_END	La collecte des données du compteur est terminée. Le paramètre Buffer contient une chaîne Unicode terminée par null qui identifie le nom de l’ordinateur (ou son adresse IP) à partir duquel le consommateur a collecté des données. Les fournisseurs peuvent utiliser cette notification pour libérer le verrou de mise à jour imposé par la notification de démarrage du regroupement afin que les mises à jour des données du compteur puissent reprendre.

[in] Buffer

Le contenu de la mémoire tampon dépend de la requête. Pour le contenu possible, consultez le paramètre RequestCode .

[in] BufferSize

Taille, en octets, du paramètre Buffer .

Valeur retournée

Retournez ERROR_SUCCESS si le rappel réussit.

Si le rappel échoue, PERFLIB retourne le code d’erreur au consommateur si la demande est PERF_ADD_COUNTER, PERF_ENUM_INSTANCES ou PERF_COLLECT_START ; sinon, le code d’erreur est ignoré.

Remarques

Si l’attribut de rappel de l’élément provider est « personnalisé » ou si vous avez utilisé l’argument -NotificationCallback lors de l’appel de CTRPP, vous devez implémenter cette fonction. Vous passez le nom de votre fonction de rappel à CounterInitialize.

Windows Vista : La fonction CounterInitialize est nommée PerfAutoInitialize. L’outil CTRPP génère également pour vous un squelette de ce rappel qui inclut tous les codes de requête. Vous ajoutez ensuite du code aux codes de demande que vous souhaitez prendre en charge et supprimez les autres.

Le rappel doit se terminer en une seconde. Si le rappel ne se termine pas à temps, PERFLIB poursuit la requête du consommateur et ignore la valeur de retour du rappel lorsqu’il se termine.

Exemples

L’exemple suivant montre une implémentation simple d’une fonction ControlCallback .

ULONG MyControlCallback(ULONG RequestCode, PVOID pBuffer, ULONG* pBufferSize)
{
    ULONG Status = ERROR_SUCCESS;
    PWNODE_HEADER Wnode = (PWNODE_HEADER)pBuffer;
    LPWSTR pComputerName = NULL;
    LPWSTR pInstance = NULL;
    PPERF_COUNTER_IDENTITY pCounter;
    UNREFERENCED_PARAMETER(pBufferSize);

    switch (RequestCode) 
    {
        case PERF_ADD_COUNTER:
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0) 
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_REMOVE_COUNTER: 
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0)
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_ENUM_INSTANCES:
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_START: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_END: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        default:
            wprintf(L"Unknown request code, %lu\n", RequestCode);
    }

    return Status;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	perflib.h

Partager via