Función OpenTraceA (evntrace.h)

  • Artículo

La función OpenTrace abre un identificador de procesamiento de seguimiento ETW para consumir eventos de una sesión de seguimiento en tiempo real de ETW o un archivo de registro ETW.

Sintaxis

TRACEHANDLE WMIAPI OpenTraceA(
  [in, out] PEVENT_TRACE_LOGFILEA Logfile
);

Parámetros

[in, out] Logfile

Puntero a una estructura de EVENT_TRACE_LOGFILE . La estructura especifica el origen del que se van a consumir eventos (de un archivo de registro ETW o de una sesión ETW en tiempo real) y especifica las devoluciones de llamada que el consumidor quiere usar para recibir los eventos. Si se ejecuta correctamente, OpenTrace actualizará la estructura con información del archivo o la sesión abiertos.

Valor devuelto

Si la función se realiza correctamente, devuelve el identificador de procesamiento de seguimiento. El identificador debe cerrarse mediante CloseTrace.

Si se produce un error en la función, devuelve INVALID_PROCESSTRACE_HANDLE. (INVALID_PROCESSTRACE_HANDLE es equivalente a (UINT64)UINTPTR_MAX).

Nota

Antes de Windows Vista, OpenTrace devolvió UINT64_MAX en caso de error. Si el código admite sistemas operativos anteriores (Windows XP o Windows Server 2003) y versiones más recientes de Windows (Windows Vista y versiones posteriores), debe determinar el sistema operativo en el que se ejecuta y comparar el valor devuelto con el valor adecuado.

Sistema operativo Tipo de proceso Valor que indica un error
Antes de Windows Vista 32 o 64 bits 0XFFFFFFFFFFFFFFFF = UINT64_MAX
Windows Vista o posterior 32 bits 0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX
Windows Vista o posterior 64 bits 0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX

Si se produce un error en la función , puede usar la función GetLastError para obtener información de error extendida. A continuación se muestran algunos errores comunes y sus causas.

  • ERROR_INVALID_PARAMETER

    El parámetro Logfile es NULL.

  • ERROR_BAD_PATHNAME

    Si no especificó el miembro LoggerName de EVENT_TRACE_LOGFILE, debe especificar un nombre de archivo de registro válido.

  • 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 consumir eventos en tiempo real. Para conceder a un usuario restringido la capacidad de consumir eventos en tiempo real, agréguelos al grupo Usuarios del registro de rendimiento.

    Windows XP y Windows 2000: Cualquier persona puede consumir eventos en tiempo real.

Comentarios

Los consumidores de seguimiento llaman a esta función para abrir una sesión de procesamiento de seguimiento.

Después de llamar a OpenTrace, llame a la función ProcessTrace para procesar los eventos. Cuando haya terminado de procesar eventos, llame a la función CloseTrace para cerrar el identificador de procesamiento de seguimiento.

Ejemplos

Para obtener un ejemplo que usa OpenTrace, consulte Uso de TdhFormatProperty para consumir datos de eventos.

Nota

El encabezado evntrace.h define OpenTrace 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

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado evntrace.h
Library Sechost.lib en Windows 8.1 y Windows Server 2012 R2; Advapi32.lib en Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista y Windows XP
Archivo DLL Sechost.dll en Windows 8.1 y Windows Server 2012 R2; Advapi32.dll en Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista y Windows XP

Consulte también

CloseTrace

EVENT_TRACE_LOGFILE

ProcessTrace