EventWriteString function (evntprov.h)

Writes an ETW event that contains a string as its data. This function should not be used.

Syntax

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

Parameters

[in] RegHandle

Registration handle of the provider. The handle comes from EventRegister. The generated event will use the ProviderId associated with the handle.

[in] Level

An 8-bit number used to describe an event's severity or importance.

See EVENT_DESCRIPTOR for details about the event level.

[in] Keyword

A 64-bit bitmask used to indicate an event's membership in a set of event categories.

See EVENT_DESCRIPTOR for details about the event keyword.

[in] String

NUL-terminated string to write as the event data.

Return value

Returns ERROR_SUCCESS if successful or an error code. Possible error codes include the following:

• ERROR_INVALID_PARAMETER: One or more of the parameters is not valid.
• ERROR_INVALID_HANDLE: The registration handle of the provider is not valid.
• ERROR_ARITHMETIC_OVERFLOW: The event size is larger than the allowed maximum (64KB - header).
• ERROR_MORE_DATA: The session buffer size is too small for the event.
• ERROR_NOT_ENOUGH_MEMORY: Occurs when filled buffers are trying to flush to disk, but disk IOs are not happening fast enough. This happens when the disk is slow and event traffic is heavy. Eventually, there are no more free (empty) buffers and the event is dropped.
• STATUS_LOG_FILE_FULL: The real-time playback file is full. Events are not logged to the session until a real-time consumer consumes the events from the playback file.

The error code is primarily intended for use in debugging and diagnostic scenarios. Most production code should continue to run and continue to report events even if an ETW event could not be written, so release builds should usually ignore the error code.

Remarks

This API is not useful and should not be used.

• Most ETW analysis tools do not correctly support string-only events without a manifest.
• Without a manifest, important information about the event (e.g. the provider name, event id, and event name) are unavailable so the resulting events are hard to use even when the analysis tool supports string-only events.
• With a manifest, this function behaves almost exactly like the code from a manifest-based event with a single string field. However, the manifest-based event is better-supported by trace analysis tools. In addition, the code generated by MC.exe for an event with a single string field is more efficient than the EventWriteString function.

Instead of using this API, consider the following alternatives:

• Use TraceLoggingProvider.h to write events that are well-supported by ETW analysis tools, work without a manifest, and include metadata like provider name and event name.
• Write an instrumentation manifest. Create a simple event with a single NUL-terminated string value. You can write and collect events even without a manifest. You will only need the manifest for decoding the collected trace.

EventWriteString writes an event with a data payload consisting of the specified string. This API is nearly equivalent to the following code:

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

The resulting event is the same as any other event generated by EventWrite except that the resulting event has the EVENT_HEADER_FLAG_STRING_ONLY flag set (see EVENT_HEADER for information about event flags).

Note that the event is written with ID, Version, Opcode, Task, and Channel set to 0.

Note that the event uses the current thread's activity ID.

ETW analysis tools that are aware of the EVENT_HEADER_FLAG_STRING_ONLY flag can extract the string value even when the decoder cannot locate any other decoding information for the event provider. However, without a manifest, the tools will not be able to determine the event's provider name.

Requirements

See also

EventWrite

TraceLoggingProvider.h