TraceEvent function (evntrace.h)
A RegisterTraceGuids-based ("Classic") event provider uses the TraceEvent function to send a structured event to an event tracing session.
Syntax
ULONG WMIAPI TraceEvent(
[in] TRACELOGGER_HANDLE TraceHandle,
[in] PEVENT_TRACE_HEADER EventTrace
);
Parameters
[in] TraceHandle
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] EventTrace
Pointer to an EVENT_TRACE_HEADER structure. Event-specific data is optionally appended to the structure. The largest event you can log is slightly less than 64K. You must specify values for the following members of the EVENT_TRACE_HEADER structure.
- Size
- Guid or GuidPtr
- Flags
Depending on the complexity of the information your provider provides, you should also consider specifying values for the following members.
- Class.Type
- Class.Level
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_FLAG_NUMBER
The Flags member of the EVENT_TRACE_HEADER structure is incorrect.
ERROR_INVALID_HANDLE
TraceHandle is not valid 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, TraceEvent discards the event.
Consider increasing the number and size of the buffers for the session, or reducing the number of events written or the size of the events.
Windows 2000: 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
One of the following is true:
- TraceHandle is NULL.
- EventTrace is NULL.
- The Size member of the EVENT_TRACE_HEADER structure is incorrect.
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
MOF-based ETW providers call this function.
Note
Most developers will not call this function. This API supports MOF-based ETW, but MOF-based ETW is deprecated in favor of manifest-based ETW. In addition, most MOF-based providers use wrapper functions generated by MC.exe instead of directly calling ETW APIs.
Before the provider can call this function, the provider
- Must call the RegisterTraceGuids function to register itself and the event trace class.
- Must be enabled. A controller calls the EnableTrace function to enable a provider.
The event is either written to a log file, sent to event trace consumers in real time, or both. The LogFileMode member of the EVENT_TRACE_PROPERTIES structure passed to the StartTrace defines where the event is sent.
The trace events are written in the order in which they occur.
To trace a set of related events, use the TraceEventInstance function.
On Windows Vista, you should use the EventWrite function to log events.
Examples
For an example that uses TraceEvent, see Tracing Events.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | evntrace.h |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |