Share via

RegisterTraceGuidsA, fonction (evntrace.h)

  • Article

La fonction RegisterTraceGuids inscrit un fournisseur de traces d’événements ETW classique (de style Windows 2000) et les classes de trace d’événements qu’elle utilise pour générer des événements. Cette fonction spécifie également la fonction de rappel que le système utilise pour activer et désactiver le suivi à partir du fournisseur.

Cette fonction est obsolète. Le nouveau code doit utiliser EventRegister pour inscrire un fournisseur de trace d’événements ETW de style Windows Vista (Crimson).

Syntaxe

ULONG WMIAPI RegisterTraceGuidsA(
  [in]      WMIDPREQUEST             RequestAddress,
  [in]      PVOID                    RequestContext,
  [in]      LPCGUID                  ControlGuid,
  [in]      ULONG                    GuidCount,
  [in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
  [in]      LPCSTR                   MofImagePath,
  [in]      LPCSTR                   MofResourceName,
  [out]     PTRACEHANDLE             RegistrationHandle
);

Paramètres

[in] RequestAddress

Pointeur vers une fonction ControlCallback qui reçoit une notification lorsque le fournisseur est activé ou désactivé par une session de suivi d’événements. La fonction EnableTrace déclenche ce rappel.

[in] RequestContext

Pointeur vers un contexte facultatif défini par le fournisseur que ETW transmet à la fonction spécifiée par RequestAddress.

[in] ControlGuid

GUID de contrôle (ID de fournisseur) du fournisseur d’inscription.

[in] GuidCount

Nombre d’éléments dans le tableau TraceGuidReg . Si TraceGuidReg a lavaleur NULL, définissez ce paramètre sur 0.

[in, out] TraceGuidReg

Pointeur vers un tableau de
TRACE_GUID_REGISTRATION structures.

Chaque élément identifie une catégorie d’événements que le fournisseur fournit.

Lors de l’entrée, le membre GUID de chaque structure contient un GUID de classe de trace d’événements attribué par le fournisseur d’inscription. Le GUID de classe identifie une catégorie d’événements que le fournisseur fournit. Les fournisseurs utilisent le même GUID de classe pour définir le membre GUID de EVENT_TRACE_HEADER lors de l’appel de la fonction TraceEvent pour journaliser l’événement.

Lors de la sortie, le membre RegHandle reçoit un handle pour l’inscription du GUID de classe de l’événement. Si le fournisseur appelle la fonction TraceEventInstance , utilisez le membre RegHandle de TRACE_GUID_REGISTRATION pour définir le membre RegHandle de EVENT_INSTANCE_HEADER.

Ce paramètre peut être NULL si le fournisseur appelle uniquement la fonction TraceEvent pour journaliser les événements. Si le fournisseur appelle la fonction TraceEventInstance pour journaliser les événements, ce paramètre ne peut pas être NULL.

[in] MofImagePath

Ce paramètre n’est pas pris en charge. Défini sur NULL. Vous devez utiliser Mofcomp.exe pour inscrire la ressource MOF lors de l’installation de votre application. Pour plus d’informations, consultez Publication de votre schéma d’événement.

Windows XP avec SP1, Windows XP et Windows 2000 : Pointeur vers une chaîne facultative qui spécifie le chemin d’accès de la DLL ou du programme exécutable qui contient la ressource spécifiée par MofResourceName. Ce paramètre peut être NULL si le fournisseur d’événements et le consommateur utilisent un autre mécanisme pour partager des informations sur les classes de trace d’événements utilisées par le fournisseur.

[in] MofResourceName

Ce paramètre n’est pas pris en charge. Défini sur NULL. Vous devez utiliser Mofcomp.exe pour inscrire la ressource MOF lors de l’installation de votre application. Pour plus d’informations, consultez Publication de votre schéma d’événement.

Windows XP avec SP1, Windows XP et Windows 2000 : Pointeur vers une chaîne facultative qui spécifie la ressource de chaîne de MofImagePath. La ressource de chaîne contient le nom du fichier MOF binaire qui décrit les classes de trace d’événements prises en charge par le fournisseur.

[out] RegistrationHandle

Reçoit le handle d’inscription du fournisseur. Utilisez le handle retourné lorsque vous appelez la fonction UnregisterTraceGuids .

Important

Tous les handles d’inscription créés par une DLL ou un pilote doivent être désinscrits avant le déchargement de la DLL ou du pilote. Si le fournisseur n’est pas désinscrit, un blocage se produit quand ETW tente d’appeler le rappel du fournisseur.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur système. Voici quelques erreurs courantes et leurs causes.

Important

 Cette fonction peut également retourner la valeur retournée par ControlCallback si un contrôleur appelle EnableTrace pour activer le fournisseur et que le fournisseur n’a pas encore appelé RegisterTraceGuids. Dans ce cas, RegisterTraceGuids retourne la valeur de retour du rappel si l’inscription a réussi.

  • ERROR_INVALID_PARAMETER

    Une des conditions suivantes est vraie :

    • RequestAddress a la valeur NULL.
    • ControlGuid a la valeur NULL.
    • RegistrationHandle a la valeur NULL.

    Windows XP et Windows 2000:TraceGuidReg a la valeur NULL ou GuidCount est inférieur ou égal à zéro.

Notes

Notes

La plupart des développeurs n’appellent pas cette fonction directement. Au lieu de cela, les développeurs utilisent généralement une infrastructure ETW. Par exemple, WPP basé sur TMF gère les appels à RegisterTraceGuids, TraceMessage et UnregisterTraceGuids en votre nom.

Cette fonction ouvre un handle de fournisseur d’événements Classic (de style Windows 2000) qui peut être utilisé pour écrire des événements WPP ETW basés sur MOF et TMF via TraceEvent, TraceEventInstance, TraceMessage et TraceMessageVa.

Notes

Pour ouvrir un handle de fournisseur de style Windows Vista qui écrit des événements ETW basés sur un manifeste ou sur TraceLogging via EventWrite, utilisez EventRegister.

Si le ControlGuid du fournisseur a été précédemment inscrit et activé, les inscriptions suivantes qui font référence au même ControlGuid sont automatiquement activées.

Un processus peut inscrire jusqu’à 1 024 GUID de fournisseur ; Toutefois, vous devez limiter à un ou deux le nombre de fournisseurs inscrits par votre processus. Cette limite inclut les personnes inscrites à l’aide de cette fonction et de la fonction EventRegister .

Avant Windows Vista : Il n’existe aucune limite au nombre de fournisseurs qu’un processus peut inscrire.

Exemples

Pour obtenir un exemple qui utilise RegisterTraceGuids, consultez Écriture d’événements classiques.

Notes

L’en-tête evntrace.h définit RegisterTraceGuids en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Spécifications

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête evntrace.h
Bibliothèque Sechost.lib sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.lib sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista et Windows XP
DLL Sechost.dll sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.dll sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista et Windows XP

Voir aussi

EnableTrace

UnregisterTraceGuids