UpdateTraceA function

The UpdateTrace function updates the property setting of the specified event tracing session.

The ControlTrace function supersedes this function.

Syntax

ULONG WMIAPI UpdateTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parameters

TraceHandle

TBD

InstanceName

TBD

Properties

TBD

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

Return code Description
ERROR_BAD_LENGTH
The BufferSize member of the Wnode member of Properties specifies an incorrect size.
ERROR_INVALID_PARAMETER
One of the following is true:
  • SessionName and SessionHandle are both NULL.
  • Properties is NULL.
  • The LogFileNameOffset member of Properties is not valid.
  • The LoggerNameOffset member of Properties is not valid.
Windows Server 2003 and Windows XP:  The Guid member of the Wnode structure is SystemTraceControlGuid, but the SessionName parameter is not KERNEL_LOGGER_NAME.
ERROR_ACCESS_DENIED
Only users with administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can control event tracing sessions. To grant a restricted user the ability to control trace sessions, add them to the Performance Log Users group.

Windows XP and Windows 2000:  Anyone can control a trace session.

Remarks

Controllers call this function.

On input, the members must specify the new values for the properties to update. You can update the following properties.

Member Use
EnableFlags Set this member to 0 to disable all kernel providers. Otherwise, you must specify the kernel providers that you want to enable or keep enabled. Applies only to NT Kernel Logger sessions.
FlushTimer Set this member if you want to change the time to wait before flushing buffers. If this member is 0, the member is not updated.
LogFileNameOffset Set this member if you want to switch to another log file. If this member is 0, the file name is not updated. If the offset is not zero and you do not change the log file name, the function returns an error.
LogFileMode Set this member if you want to turn EVENT_TRACE_REAL_TIME_MODE on and off. To turn real time consuming off, set this member to 0. To turn real time consuming on, set this member to EVENT_TRACE_REAL_TIME_MODE and it will be OR'd with the current modes.
MaximumBuffers Set set this member if you want to change the maximum number of buffers that ETW uses. If this member is 0, the member is not updated.
 

For private logger sessions, you can only update LogFileNameOffset and FlushTimer.

If you are using a newly initialized EVENT_TRACE_PROPERTIES structure, the only members you need to specify, other than the members you are updating, are Wnode.BufferSize, Wnode.Guid, and Wnode.Flags.

If you use the property structure you passed to StartTrace, make sure the LogFileNameOffset member is 0 unless you are changing the log file name.

If you call the ControlTrace function to query the current session properties and then update those properties to update the session, make sure you set LogFileNameOffset to 0 (unless you are changing the log file name) and set EVENT_TRACE_PROPERTIES.Wnode.Flags to WNODE_FLAG_TRACED_GUID.

To obtain the property settings and session statistics for an event tracing session, call the ControlTrace function.

Examples

For an example that uses UpdateTrace, see Updating an Event Tracing Session.

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

ControlTrace