WmiTraceMessage function

The WmiTraceMessage routine adds a message to the output log of a WPP software tracing session.

Syntax

NTSTATUS WmiTraceMessage(
  TRACEHANDLE LoggerHandle,
  ULONG       MessageFlags,
  LPCGUID     MessageGuid,
  USHORT      MessageNumber,
  ...         
);

Parameters

LoggerHandle

Specifies a trace handle for a software tracing session.

MessageFlags

Specifies a bitwise OR of one or more message flags. See the Remarks section for details.

MessageGuid

Specifies a GUID that identifies the class of software trace messages.

MessageNumber

Identifies the message subtype. The meaning of subtypes is specific to the software trace class and the provider.

Arg1

Return Value

WmiTraceMessage returns one of the following values:

Return code Description
STATUS_SUCCESS
The operation completed successfully.
STATUS_INVALID_HANDLE
LoggerHandle is not a valid software trace handle.
STATUS_NO_MEMORY
There is insufficient buffer memory to log the message. See the Remarks section.
Other NTSTATUS value
An internal error occurred.

Remarks

A caller can use WmiTraceMessage or WmiTraceMessageVa to add a message to the output log of a WPP software tracing session. WmiTraceMessage simplifies a caller's code by handling the variable list mechanism before calling WmiTraceMessageVa.

A caller can set the following message flags:

Flag Description
TRACE_MESSAGE_SEQUENCE Include a sequence number in the message. Message sequencing can only be used if it is set for the software tracing session specified by LoggerHandle.
TRACE_MESSAGE_GUID MessageGuid specifies a GUID that identifies a software trace class. This flag must be set.
TRACE_MESSAGE_TIMESTAMP Include a time stamp in the message.
TRACE_MESSAGE_PERFORMANCE_TIMESTAMP This flag is not implemented and is obsolete. It must not be used.
TRACE_MESSAGE_SYSTEMINFO Include the thread identifier (TID) and process identifier (PID) in the message.

A message will not be logged if one of the following is true:

  • The total size, in bytes, of the message data and the message header is greater than the size of individual message buffers allocated for a software tracing session. (The maximum message header size is 48 bytes.)

  • All message buffers allocated to software tracing session are full.

WmiTraceMessage runs at the IRQL of the caller.

Requirements

   
Windows version Available in Windows XP and later versions of Windows.
Target Platform Universal
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL See Remarks section.

See Also

IoWmiWriteEvent

TRACE_INFORMATION_CLASS

WmiFireEvent

WmiQueryTraceInformation

WmiTraceMessageVa