RegisterTraceGuidsA, fonction (evntrace.h)
La fonction
Cette fonction est obsolète. Le nouveau code doit utiliser
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] TRACEGUID_HANDLE *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 un fournisseur transmis à 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 est NULL, définissez ce paramètre sur 0.
[in, out] TraceGuidReg
Pointeur vers un tableau de
structures TRACE_GUID_REGISTRATION.
Chaque élément identifie une catégorie d’événements que le fournisseur fournit.
Lors de l’entrée, le guid membre de chaque structure contient un GUID de classe de trace d’événements affecté 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 consigner l’événement.
En sortie, le membre RegHandle reçoit un handle à l’inscription GUID de classe de l’événement. Si le fournisseur appelle la fonction TraceEventInstance
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 pendant la configuration 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 pendant la configuration 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 inscrit, un incident se produit lorsque ETW tente d’appeler le rappel du fournisseur.
Valeur de retour
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. Lorsque cela se produit, RegisterTraceGuids retourne la valeur de retour du rappel si l’inscription a réussi.
ERROR_INVALID_PARAMETER
L’une des valeurs suivantes est vraie :
- RequestAddress est NULL.
- ControlGuid est NULL.
- RegistrationHandle est NULL.
Windows XP et Windows 2000 :TraceGuidReg est NULL ou GuidCount est inférieur ou égal à zéro.
Remarques
Note
La plupart des développeurs n’appelleront pas cette fonction directement. Au lieu de cela, les développeurs utiliseront généralement une infrastructure ETW. Par exemple, WPP basé sur TMF gère les appels à RegisterTraceGuids, TraceMessageet UnregisterTraceGuids en votre nom.
Cette fonction ouvre un handle de fournisseur d’événements classique
Note
Pour ouvrir un de fournisseur de de style Windows Vista qui écrit des événements ETW basés sur un manifeste ou 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 le nombre de fournisseurs que votre processus s’inscrit à un ou deux. Cette limite inclut celles 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.
Note
L’en-tête evntrace.h définit RegisterTraceGuids comme 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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’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 |