CreateTraceInstanceId function (evntrace.h)

Article
02/22/2024

A RegisterTraceGuids-based ("Classic") event provider may use the CreateTraceInstanceId function to create a unique transaction identifier and map it to a registration handle. The provider then uses the transaction identifier when calling the TraceEventInstance function to mark events as belonging to the specified transaction. The transaction identifier can be used by trace analysis tools to group events.

Syntax

ULONG WMIAPI CreateTraceInstanceId(
  [in]  HANDLE               RegHandle,
  [out] PEVENT_INSTANCE_INFO InstInfo
);

Parameters

[in] RegHandle

Handle to a registered event trace class. The RegisterTraceGuids function returns this handle in the RegHandle member of the TRACE_GUID_REGISTRATION structure.

[out] InstInfo

Pointer to an EVENT_INSTANCE_INFO structure. The InstanceId member of this structure contains the transaction identifier.

Return value

If the function is successful, 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_PARAMETER

One of the following is true:
- RegHandle is NULL.
- pInstInfo is NULL.

Remarks

RegisterTraceGuids-based ("Classic") providers call this function. Use EventActivityIdControl for similar functionality with an EventRegister-based ("Crimson") provider.

ETW creates the identifier in the user-mode process, so it might return the same number for different instances in different processes. The value starts over at 1 when InstanceId reaches the maximum value for a ULONG. Only user-mode providers can call the CreateTraceInstanceId function (drivers cannot call this function).

Examples

For an example that uses CreateTraceInstanceId, see Tracing Event Instances.

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

Share via