UpdateHeapTrace

  • Article

This function updates an existing heap tracing session with a new set of PIDs, stackwalking events, or other ETW session changes.

ULONG
WINAPI
UpdateHeapTrace(
    _Inout_ PEVENT_TRACE_PROPERTIES Properties,
    _In_z_ LPCWSTR wszSessionName,
    _In_reads_opt_(cPids) const ULONG Pids[],
    _In_  ULONG cPids,
    _In_reads_opt_(cStackTracingEventIds) const STACK_TRACING_EVENT_ID StackTracingEventIds[],
    _In_  ULONG cStackTracingEventIds
    );

Parameters

TraceHandle [out]
Stores a handle to an event tracing session. This parameter is set to zero if the handle is not valid. This parameter should not be compared to INVALID_HANDLE_VALUE. Do not use this handle if the function fails.

Properties [in, out]
A pointer to an EVENT_TRACE_PROPERTIES structure with updated properties for the session. Refer to the ControlTrace function with ControlCode EVENT_TRACE_CONTROL_UPDATE for details about which members of this structure can be specified.

wszSessionName[in]
The name of the heap tracing session to update. This should be the same name that was passed to StartHeapTrace.

Pids [in]
An array of process IDs to enable heap tracing on.

cPids [in, out]
The size of the Pids array.

StackTracingEventIds [in]
An array of STACK_TRACING_EVENT_ID structures specifying which heap events stack walking should be enabled for. Can be NULL.

cStackTracingEventIds [in]
The size of the StackTracingEventIds array.

Return Value

ERROR_SUCCESS indicates success.

Possible error values are described in the following table.

Error Value Description

ERROR_ALREADY_EXISTS

Only a single instance of the kernel logger runs on the system. If this function attempts to start after another component has started kernel logging, this error is possibly returned.

ERROR_INVALID_FLAGS

Possibly indicates that there are invalid trace flags in Properties.EnableFlags.

ERROR_OUT_OF_MEMORY

Possibly indicates failure to allocate memory for EVENT_TRACE_PROPERTIES.

If the function fails for a reason other than those listed, a system error code is returned.

Remarks

None

Functions

StartHeapTrace