EventWriteTransfer-Funktion (evntprov.h)

Schreibt ein ETW-Ereignis mit einer Aktivitäts-ID und einer optionalen zugehörigen Aktivitäts-ID.

Syntax

ULONG EVNTAPI EventWriteTransfer(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parameter

[in] RegHandle

Registrierungshandle des Anbieters. Das Handle stammt aus EventRegister. Das generierte Ereignis verwendet die dem Handle zugeordnete ProviderId.

[in] EventDescriptor

EVENT_DESCRIPTOR mit Ereignisinformationen (Metadaten), einschließlich ID, Version, Ebene, Schlüsselwort, Kanal, Opcode und Task.

[in, optional] ActivityId

Ein optionaler Zeiger auf eine 128-Bit-Aktivitäts-ID für dieses Ereignis. Wenn dies nicht NULL ist, verwendet EventWriteTransfer den angegebenen Wert für die Aktivitäts-ID des Ereignisses. Wenn dies NULL ist, verwendet EventWriteTransfer die Aktivitäts-ID des aktuellen Threads.

Ablaufverfolgungsverarbeitungstools können die Aktivitäts-ID des Ereignisses verwenden, um Ereignisse in Gruppen zu organisieren, die als Aktivitäten bezeichnet werden. Weitere Informationen zur Aktivitäts-ID finden Sie unter EventActivityIdControl.

[in, optional] RelatedActivityId

Ein optionaler Zeiger auf eine 128-Bit-Aktivitäts-ID, die das übergeordnete Element der Aktivität dieses Ereignisses ist. Wenn dies nicht NULL ist, verwendet EventWriteTransfer den angegebenen Wert für die zugehörige Aktivitäts-ID des Ereignisses. Wenn dies NULL ist, weist das Ereignis keine zugehörige Aktivitäts-ID auf. Die zugehörige Aktivitäts-ID wird normalerweise für das START-Ereignis der Aktivität festgelegt (das erste Ereignis der Aktivität, protokolliert mit Opcode = START).

Ablaufverfolgungsverarbeitungstools können die zugehörige Aktivitäts-ID des Ereignisses verwenden, um die Beziehung zwischen Aktivitäten zu bestimmen, z. B. ist die zugehörige Aktivität das übergeordnete Element der neu gestarteten Aktivität. Weitere Informationen zur zugehörigen Aktivitäts-ID finden Sie unter EventActivityIdControl.

[in] UserDataCount

Anzahl der EVENT_DATA_DESCRIPTOR Strukturen in UserData. Die maximale Anzahl ist 128.

[in, optional] UserData

Ein Array von UserDataCountEVENT_DATA_DESCRIPTOR Strukturen, die die Daten beschreiben, die in das Ereignis eingeschlossen werden sollen. UserData kann NULL sein, wenn UserDataCount null ist.

Jeder EVENT_DATA_DESCRIPTOR beschreibt einen Speicherblock, der in das Ereignis eingeschlossen werden soll. Die angegebenen Blöcke werden in der Reihenfolge verkettet, ohne dass der Inhalt des Ereignisses aufgefüllt oder ausgerichtet ist. Bei Verwendung der manifestbasierten Decodierung muss der Ereignisinhalt mit dem Layout übereinstimmen, das in der Vorlage angegeben ist, die dem Ereignis im Manifest zugeordnet ist.

Rückgabewert

Gibt ERROR_SUCCESS zurück, wenn erfolgreich oder ein Fehlercode vorhanden ist. Mögliche Fehlercodes sind:

• ERROR_INVALID_PARAMETER: Mindestens ein Parameter ist ungültig.
• ERROR_INVALID_HANDLE: Das Registrierungshandle des Anbieters ist ungültig.
• ERROR_ARITHMETIC_OVERFLOW: Die Ereignisgröße ist größer als das zulässige Maximum (64 KB – Header).
• ERROR_MORE_DATA: Die Sitzungspuffergröße ist für das Ereignis zu klein.
• ERROR_NOT_ENOUGH_MEMORY: Tritt auf, wenn gefüllte Puffer versuchen, auf den Datenträger zu leeren, Datenträger-IOs jedoch nicht schnell genug ausgeführt werden. Dies geschieht, wenn der Datenträger langsam ist und der Ereignisdatenverkehr hoch ist. Schließlich gibt es keine freien (leeren) Puffer mehr, und das Ereignis wird gelöscht.
• STATUS_LOG_FILE_FULL: Die Echtzeitwiedergabedatei ist voll. Ereignisse werden erst in der Sitzung protokolliert, wenn ein Echtzeitconsumer die Ereignisse aus der Wiedergabedatei nutzt.

Der Fehlercode ist in erster Linie für die Verwendung in Debug- und Diagnoseszenarien vorgesehen. Der meiste Produktionscode sollte weiterhin ausgeführt werden und weiterhin Ereignisse melden, auch wenn ein ETW-Ereignis nicht geschrieben werden konnte. Daher sollten Releasebuilds den Fehlercode in der Regel ignorieren.

Hinweise

Die meisten Ereignisanbieter rufen EventWriteTransfer nicht direkt auf. Stattdessen werden die meisten Ereignisanbieter mithilfe eines ETW-Frameworks implementiert, das die Aufrufe von EventRegister, EventWriteTransfer und EventUnregister umschließt. Sie können beispielsweise ein Ereignismanifest schreiben und dann den Nachrichtencompiler verwenden, um C/C++-Code für die Ereignisse zu generieren, oder Sie können TraceLogging verwenden, um die Notwendigkeit eines Manifests zu vermeiden.

EventWriteTransfer leitet das Ereignis an die entsprechenden Ablaufverfolgungssitzungen basierend auf der ProviderId (ermittelt aus regHandle), Level, Keyword und anderen Ereignismerkmalen weiter. Wenn dieses Ereignis nicht von Ablaufverfolgungssitzungen aufgezeichnet wird, führt diese Funktion nichts aus und gibt ERROR_SUCCESS zurück.

Um die Auswirkungen auf die Leistung von Ereignissen zu verringern, die von keiner Ablaufverfolgungssitzung aufgezeichnet werden, können Sie EventEnabled aufrufen, um zu bestimmen, ob eine Ablaufverfolgungssitzung Ihr Ereignis vor dem Vorbereiten der Daten und aufrufen EventWriteTransfer aufzeichnet.

EventWriteTransfer entspricht EventWriteEx mit 0 für Filter und 0 für Flags.

Anforderungen

Weitere Informationen

EventActivityIdControl

EventRegister

EventWrite

EventWriteEx

Schreiben von manifestbasierten Ereignissen.