TraceMessageVa-Funktion (evntrace.h)

  • Artikel

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

Syntax

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

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_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.

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

  • Sequenznummer
  • GUID der Ereignisablaufverfolgungsklasse
  • Zeitstempel
  • Threadbezeichner
  • Prozessbezeichner

[in] MessageGuid

Klassen-GUID, die die Ereignisablaufverfolgungsmeldung identifiziert.

[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.

[in] MessageArgList

Liste der Variablenargumente, die an die Nachricht angefügt werden sollen. Die Liste muss wie folgt aus Argumentpaaren 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. Die folgende Tabelle enthält 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 nicht über eine Wrapperfunktion auf die Nachrichtenablaufverfolgungsfunktion zugreifen müssen, können Sie die TraceMessage-Version dieser Funktion aufrufen.

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 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile evntrace.h
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

Traceevent

TraceEventInstance

TraceMessage