Share via

Función UpdateTraceW (evntrace.h)

  • Artículo

La función UpdateTrace actualiza el valor de propiedad de la sesión de seguimiento de eventos especificada.

Esta función está obsoleta. La función ControlTrace sustituye a esta función.

Sintaxis

ULONG WMIAPI UpdateTraceW(
  TRACEHANDLE             TraceHandle,
  LPCWSTR                 InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parámetros

TraceHandle

Controle la sesión de seguimiento de eventos que se va a actualizar o 0. Debe especificar un valor TraceHandle distinto de cero si InstanceName es NULL. Este parámetro solo se usará si InstanceName es NULL. StartTrace devuelve el identificador.

InstanceName

Nombre de la sesión de seguimiento de eventos que se va a actualizar o NULL. Debe especificar InstanceName si TraceHandle es 0.

Para especificar la sesión del registrador de kernel de NT, establezca InstanceName en KERNEL_LOGGER_NAME.

Properties

Puntero a una estructura de EVENT_TRACE_PROPERTIES inicializada.

En la entrada, los miembros deben especificar los nuevos valores de las propiedades que se van a actualizar. Para obtener información sobre las propiedades que puede actualizar, vea Comentarios.

En la salida, los miembros de la estructura contienen la configuración actualizada y las estadísticas de la sesión de seguimiento de eventos.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es uno de los códigos de error del sistema. En la tabla siguiente se incluyen algunos errores comunes y sus causas.

  • ERROR_BAD_LENGTH

    El miembro BufferSize del miembro Wnode de Properties especifica un tamaño incorrecto.

  • ERROR_INVALID_PARAMETER

    Una de las siguientes condiciones se cumple:

    • Las propiedades son NULL.
    • InstanceName y TraceHandle son NULL.
    • InstanceName es NULL y TraceHandle no es un identificador válido.
    • El miembro LogFileNameOffset de Properties no es válido.
    • El miembro LoggerNameOffset de Properties no es válido.

    Windows Server 2003 y Windows XP: El miembro Guid de la estructura Wnode es SystemTraceControlGuid, pero el parámetro InstanceName no es KERNEL_LOGGER_NAME.

  • ERROR_ACCESS_DENIED

    Solo los usuarios con privilegios administrativos, los usuarios del grupo Usuarios del registro de rendimiento y los servicios que se ejecutan como LocalSystem, LocalService, NetworkService pueden controlar las sesiones de seguimiento de eventos. Para conceder a un usuario restringido la capacidad de controlar las sesiones de seguimiento, agréguelas al grupo Usuarios del registro de rendimiento.

    Windows XP y Windows 2000: Cualquier persona puede controlar una sesión de seguimiento.

Comentarios

Los controladores de seguimiento de eventos llaman a esta función.

Esta función está obsoleta. En su lugar, use ControlTrace con ControlCode establecido en EVENT_TRACE_CONTROL_UPDATE.

En la entrada, los miembros deben especificar los nuevos valores de las propiedades que se van a actualizar. Puede actualizar las siguientes propiedades.

  • EnableFlags: establezca este miembro en 0 para deshabilitar todos los proveedores de kernel. De lo contrario, debe especificar los proveedores de kernel que desea habilitar o mantener habilitados. Solo se aplica a las sesiones del registrador del sistema.

  • FlushTimer: establezca este miembro si desea cambiar el tiempo de espera antes de vaciar los búferes. Si este miembro es 0, el miembro no se actualiza.

  • LogFileNameOffset: establezca este miembro si desea cambiar a otro archivo de registro. Si este miembro es 0, el nombre de archivo no se actualiza. Si el desplazamiento no es cero y no cambia el nombre del archivo de registro, la función devuelve un error.

  • LogFileMode: establezca este miembro si desea activar y desactivar EVENT_TRACE_REAL_TIME_MODE . Para desactivar el tiempo real, establezca este miembro en 0. Para activar el tiempo real, establezca este miembro en EVENT_TRACE_REAL_TIME_MODE y será OR con los modos actuales.

  • MaximumBuffers: establezca este miembro si desea cambiar el número máximo de búferes que usa ETW. Si este miembro es 0, el miembro no se actualiza.

En el caso de las sesiones de registrador privados, solo puede actualizar LogFileNameOffset y FlushTimer.

Si usa una estructura de EVENT_TRACE_PROPERTIES recién inicializada, los únicos miembros que necesita especificar, excepto los miembros que está actualizando, son Wnode.BufferSize, Wnode.Guid y Wnode.Flags.

Si usa la estructura de propiedades que pasó a StartTrace, asegúrese de que el miembro LogFileNameOffset sea 0 a menos que cambie el nombre del archivo de registro.

Si llama a la función ControlTrace para consultar las propiedades de la sesión actual y, a continuación, actualiza esas propiedades para actualizar la sesión, asegúrese de establecer LogFileNameOffset en 0 (a menos que cambie el nombre del archivo de registro) y establezca EVENT_TRACE_PROPERTIES. Wnode.Flags para WNODE_FLAG_TRACED_GUID.

Para obtener la configuración de propiedades y las estadísticas de sesión de una sesión de seguimiento de eventos, llame a la función ControlTrace .

Ejemplos

Para obtener un ejemplo que usa UpdateTrace, consulte Actualización de una sesión de seguimiento de eventos.

Nota

El encabezado evntrace.h define UpdateTrace como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

   
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado evntrace.h
Library Advapi32.lib
Archivo DLL Advapi32.dll

Consulte también

ControlTrace