CreateTraceInstanceId, fonction (evntrace.h)
Un fournisseur d’événements basé sur RegisterTraceGuids (« Classique ») peut utiliser la fonction CreateTraceInstanceId pour créer un identificateur de transaction unique et le mapper à un handle d’inscription. Le fournisseur utilise ensuite l’identificateur de transaction lors de l’appel de la fonction TraceEventInstance pour marquer les événements comme appartenant à la transaction spécifiée. L’identificateur de transaction peut être utilisé par les outils d’analyse des traces pour regrouper des événements.
Syntaxe
ULONG WMIAPI CreateTraceInstanceId(
[in] HANDLE RegHandle,
[out] PEVENT_INSTANCE_INFO InstInfo
);
Paramètres
[in] RegHandle
Gérez une classe de trace d’événement inscrite. La fonction RegisterTraceGuids retourne ce handle dans le membre RegHandle de la structure TRACE_GUID_REGISTRATION .
[out] InstInfo
Pointeur vers une structure EVENT_INSTANCE_INFO . Le membre InstanceId de cette structure contient l’identificateur de transaction.
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.
ERROR_INVALID_PARAMETER
Une des conditions suivantes est vraie :
- RegHandle a la valeur NULL.
- pInstInfo a la valeur NULL.
Remarques
Les fournisseurs basés sur RegisterTraceGuids (« Classic ») appellent cette fonction. Utilisez EventActivityIdControl pour des fonctionnalités similaires avec un fournisseur basé sur EventRegister (« Crimson »).
ETW crée l’identificateur dans le processus en mode utilisateur, de sorte qu’il peut retourner le même nombre pour différentes instances dans différents processus. La valeur démarre à partir du 1 moment où InstanceId atteint la valeur maximale pour un ULONG. Seuls les fournisseurs en mode utilisateur peuvent appeler la fonction CreateTraceInstanceId (les pilotes ne peuvent pas appeler cette fonction).
Exemples
Pour obtenir un exemple qui utilise CreateTraceInstanceId, consultez Tracing Event Instances.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | evntrace.h |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |