Edit

Share via

TraceMessage function (evntrace.h)

  • Article

A RegisterTraceGuids-based ("Classic") event provider uses the TraceMessage function to send a message-based (TMF-based WPP) event to an event tracing session.

Syntax

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

Parameters

[in] LoggerHandle

Handle to the event tracing session that records the event. The provider obtains the handle when it calls the GetTraceLoggerHandle function in its ControlCallback implementation.

[in] MessageFlags

Adds additional information to the beginning of the provider-specific data section of the event. The provider-specific data section of the event will contain data only for those flags that are set. The variable list of argument data will follow this information. This parameter can be one or more of the following values.

  • TRACE_MESSAGE_COMPONENTID

    Include the component identifier in the message. The MessageGuid parameter contains the component identifier.

  • TRACE_MESSAGE_GUID

    Include the event trace class GUID in the message. The MessageGuid parameter contains the event trace class GUID.

  • TRACE_MESSAGE_SEQUENCE

    Include a sequence number in the message. The sequence number starts at one. To use this flag, the controller must have set the EVENT_TRACE_USE_GLOBAL_SEQUENCE or EVENT_TRACE_USE_LOCAL_SEQUENCE log file mode when creating the session.

  • TRACE_MESSAGE_SYSTEMINFO

    Include the thread identifier and process identifier in the message.

  • TRACE_MESSAGE_TIMESTAMP

    Include a time stamp in the message.

TRACE_MESSAGE_COMPONENTID and TRACE_MESSAGE_GUID are mutually exclusive.

The information is included in the event data in the following order:

  • Sequence number
  • Event trace class GUID (or component identifier)
  • Time stamp
  • Thread identifier
  • Process identifier

[in] MessageGuid

Class GUID or component ID that identifies the message. Depends if MessageFlags contains the TRACE_MESSAGE_COMPONENTID or TRACE_MESSAGE_GUID flag.

[in] MessageNumber

Number that uniquely identifies each occurrence of the message. You must define the value specified for this parameter; the value should be meaningful to the application.

...

A list of variable arguments to be appended to the message. Use this list to specify your provider-specific event data. The list must be composed of pairs of arguments as follows.

  • PVOID: Pointer to the argument data.
  • size_t: The size of the argument data, in bytes.

Terminate the list using an argument pair consisting of a pointer to NULL and zero.

The caller must ensure that the sum of the sizes of the arguments + 72 does not exceed the size of the event tracing session's buffer.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the system error codes. The following are some common errors and their causes.

  • ERROR_INVALID_HANDLE

    Either the LoggerHandle is NULL or specifies the NT Kernel Logger session handle.

  • ERROR_NOT_ENOUGH_MEMORY

    The session ran out of free buffers to write to. This can occur during high event rates because the disk subsystem is overloaded or the number of buffers is too small. Rather than blocking until more buffers become available, TraceMessage discards the event.

    Windows 2000 and Windows XP: Not supported.

  • ERROR_OUTOFMEMORY

    The event is discarded because, although the buffer pool has not reached its maximum size, there is insufficient available memory to allocate an additional buffer and there is no buffer available to receive the event.

  • ERROR_INVALID_PARAMETER

    MessageFlags contains a value that is not valid.

  • ERROR_MORE_DATA

    Data from a single event cannot span multiple buffers. A trace event is limited to the size of the event tracing session's buffer minus the size of the EVENT_TRACE_HEADER structure.

Remarks

TMF-based WPP providers call this function.

Note

Most developers will not call this function directly. WPP providers use wrapper functions generated by tracewpp.exe instead of calling ETW APIs.

If you need to access message tracing functionality from a wrapper function, call the TraceMessageVa version of this function.

Consumers will have to use the EventCallback callback to receive and process the events if the MessageFlags parameter does not contain the TRACE_MESSAGE_GUID flag. If you do not specify the TRACE_MESSAGE_GUID flag, the consumer will not be able to use the EventClassCallback because the Header.Guid member of the EVENT_TRACE structure will not contain the event trace class GUID.

Note that the members of the EVENT_TRACE and EVENT_TRACE_HEADER structures that correspond to the MessageFlags flags are set only if the corresponding flag is specified. For example, the ThreadId and ProcessId members of EVENT_TRACE_HEADER are populated only if you specify the TRACE_MESSAGE_SYSTEMINFO flag.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps | UWP apps]
Minimum supported server Windows Server 2003 [desktop apps | UWP apps]
Target Platform Windows
Header evntrace.h
Library Advapi32.lib
DLL Advapi32.dll

See also

TraceEvent

TraceEventInstance

TraceMessageVa