TraceMessage-Funktion (evntrace.h)

  • Artikel

Ein RegisterTraceGuids-basierter ("Classic")-Ereignisanbieter verwendet die TraceMessage-Funktion , um ein nachrichtenbasiertes (TMF-basiertes WPP)-Ereignis an eine Ereignisablaufverfolgungssitzung zu senden.

Syntax

ULONG TraceMessage(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
       ...         
);

Parameter

[in] LoggerHandle

Behandeln Sie die Ereignisablaufverfolgungssitzung, die das Ereignis aufzeichnet. Der Anbieter ruft das Handle ab, wenn er die GetTraceLoggerHandle-Funktion in seiner ControlCallback-Implementierung aufruft.

[in] MessageFlags

Fügt dem Anfang des anbieterspezifischen Datenabschnitts des Ereignisses zusätzliche Informationen hinzu. Der anbieterspezifische Datenabschnitt des Ereignisses enthält nur Daten für die flags, die festgelegt sind. Die Variablenliste der Argumentdaten folgt diesen Informationen. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

  • TRACE_MESSAGE_COMPONENTID

    Schließen Sie den Komponentenbezeichner in die Nachricht ein. Der MessageGuid-Parameter enthält den Komponentenbezeichner.

  • TRACE_MESSAGE_GUID

    Fügen Sie die GUID der Ereignisablaufverfolgungsklasse in die Nachricht ein. Der MessageGuid-Parameter enthält die Ereignisablaufverfolgungsklasse-GUID.

  • TRACE_MESSAGE_SEQUENCE

    Fügen Sie eine Sequenznummer in die Nachricht ein. Die Sequenznummer beginnt bei 1. Um dieses Flag verwenden zu können, muss der Controller beim Erstellen der Sitzung den EVENT_TRACE_USE_GLOBAL_SEQUENCE - oder EVENT_TRACE_USE_LOCAL_SEQUENCE Protokolldateimodus festgelegt haben.

  • TRACE_MESSAGE_SYSTEMINFO

    Fügen Sie den Threadbezeichner und den Prozessbezeichner in die Nachricht ein.

  • TRACE_MESSAGE_TIMESTAMP

    Fügen Sie einen Zeitstempel in die Nachricht ein.

TRACE_MESSAGE_COMPONENTID und TRACE_MESSAGE_GUID schließen sich gegenseitig aus.

Die Informationen sind in den Ereignisdaten in der folgenden Reihenfolge enthalten:

  • Sequenznummer
  • GUID der Ereignisablaufverfolgungsklasse (oder Komponentenbezeichner)
  • Zeitstempel
  • Threadbezeichner
  • Prozessbezeichner

[in] MessageGuid

Klassen-GUID oder Komponenten-ID, die die Nachricht identifiziert. Hängt davon ab, ob MessageFlags das flag TRACE_MESSAGE_COMPONENTID oder TRACE_MESSAGE_GUID enthält.

[in] MessageNumber

Zahl, die jedes Vorkommen der Nachricht eindeutig identifiziert. Sie müssen den für diesen Parameter angegebenen Wert definieren. Der Wert sollte für die Anwendung aussagekräftig sein.

...

Eine Liste von Variablenargumenten, die an die Nachricht angefügt werden sollen. Verwenden Sie diese Liste, um Ihre anbieterspezifischen Ereignisdaten anzugeben. Die Liste muss wie folgt aus Paaren von Argumenten bestehen.

  • PVOID: Zeiger auf die Argumentdaten.
  • size_t: Die Größe der Argumentdaten in Bytes.

Beenden Sie die Liste mit einem Argumentpaar, das aus einem Zeiger auf NULL und 0 besteht.

Der Aufrufer muss sicherstellen, dass die Summe der Größen der Argumente + 72 die Größe des Puffers der Ereignisablaufverfolgungssitzung nicht überschreitet.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der Systemfehlercodes. Im Folgenden finden Sie einige häufige Fehler und deren Ursachen.

  • ERROR_INVALID_HANDLE

    Entweder ist loggerHandleNULL oder gibt das Nt Kernel Logger-Sitzungshandle an.

  • ERROR_NOT_ENOUGH_MEMORY

    Es sind nicht genügend freie Puffer zum Schreiben der Sitzung vorhanden. Dieser Fall kann während hoher Ereignisraten auftreten, weil das Datenträgersubsystem überlastet ist oder nicht genügend Puffer vorhanden sind. Anstatt zu blockieren, bis mehr Puffer verfügbar sind, verwirft TraceMessage das Ereignis.

    Windows 2000 und Windows XP: Nicht unterstützt.

  • ERROR_OUTOFMEMORY

    Das Ereignis wird verworfen, da, obwohl der Pufferpool seine maximale Größe nicht erreicht hat, nicht genügend Arbeitsspeicher verfügbar ist, um einen zusätzlichen Puffer zuzuweisen, und es ist kein Puffer für den Empfang des Ereignisses verfügbar.

  • ERROR_INVALID_PARAMETER

    MessageFlags enthält einen ungültigen Wert.

  • ERROR_MORE_DATA

    Daten aus einem einzelnen Ereignis können sich nicht über mehrere Puffer erstrecken. Ein Ablaufverfolgungsereignis ist auf die Größe des Puffers der Ereignisablaufverfolgungssitzung abzüglich der Größe der EVENT_TRACE_HEADER-Struktur beschränkt.

Hinweise

TMF-basierte WPP-Anbieter rufen diese Funktion auf.

Hinweis

Die meisten Entwickler rufen diese Funktion nicht direkt auf. WPP-Anbieter verwenden von tracewpp.exe generierte Wrapperfunktionen, anstatt ETW-APIs aufzurufen.

Wenn Sie über eine Wrapperfunktion auf die Nachrichtenablaufverfolgungsfunktion zugreifen müssen, rufen Sie die TraceMessageVa-Version dieser Funktion auf.

Consumer müssen den EventCallback-Rückruf verwenden, um die Ereignisse zu empfangen und zu verarbeiten, wenn der MessageFlags-Parameter nicht das flag TRACE_MESSAGE_GUID enthält. Wenn Sie das TRACE_MESSAGE_GUID-Flag nicht angeben, kann der Consumer eventClassCallback nicht verwenden, da das Header.Guid-Element der EVENT_TRACE-Struktur die Ereignisablaufverfolgungsklassen-GUID nicht enthält.

Beachten Sie, dass die Member der EVENT_TRACE - und EVENT_TRACE_HEADER-Strukturen , die den MessageFlags-Flags entsprechen, nur festgelegt werden, wenn das entsprechende Flag angegeben ist. Beispielsweise werden die ThreadId - und ProcessId-Member von EVENT_TRACE_HEADER nur aufgefüllt, wenn Sie das flag TRACE_MESSAGE_SYSTEMINFO angeben.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntrace.h
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

Traceevent

TraceEventInstance

TraceMessageVa