Edit

CreateTraceInstanceId function (evntrace.h)

  • Article

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

See also

RegisterTraceGuids

TraceEventInstance