CreateTraceInstanceId function

The CreateTraceInstanceId function creates a unique transaction identifier and maps it to a class GUID registration handle. You then use the transaction identifier when calling the TraceEventInstance function.

Syntax

ULONG WMIAPI CreateTraceInstanceId(
  HANDLE               RegHandle,
  PEVENT_INSTANCE_INFO InstInfo
);

Parameters

RegHandle

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

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 table includes some common errors and their causes.

Return code Description
ERROR_INVALID_PARAMETER
One of the following is true:
  • RegHandle is NULL.
  • pInstInfo is NULL.

Remarks

Providers call this function.

ETW creates the identifier in the user-mode process, thus it can return the same number for different processes. The value starts over at one 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

   
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