Función TdhFormatProperty (tdh.h)

Da formato a un valor de propiedad para mostrar.

Sintaxis

TDHSTATUS TdhFormatProperty(
  [in]            PTRACE_EVENT_INFO EventInfo,
  [in, optional]  PEVENT_MAP_INFO   MapInfo,
  [in]            ULONG             PointerSize,
  [in]            USHORT            PropertyInType,
  [in]            USHORT            PropertyOutType,
  [in]            USHORT            PropertyLength,
  [in]            USHORT            UserDataLength,
  [in]            PBYTE             UserData,
  [in, out]       PULONG            BufferSize,
  [out, optional] PWCHAR            Buffer,
  [out]           PUSHORT           UserDataConsumed
);

Parámetros

[in] EventInfo

Estructura TRACE_EVENT_INFO que contiene la información del evento. Para obtener esta estructura, llame a la función TdhGetEventInformation.

[in, optional] MapInfo

Estructura EVENT_MAP_INFO que asigna valores enteros y de bits a cadenas. Para obtener esta estructura, llame a la función TdhGetEventMapInformation. Para obtener el nombre del mapa, use el miembro MapNameOffset de la estructura EVENT_PROPERTY_INFO. Si no proporciona la información de mapa para una propiedad asignada, la función da formato al valor entero o bit.

[in] PointerSize

Tamaño de un valor de puntero en los datos del evento. Para obtener el tamaño, acceda al EVENT_RECORD. Miembro EventHeader.Flags . El tamaño del puntero es de 4 bytes si se establece la marca EVENT_HEADER_FLAG_32_BIT_HEADER; de lo contrario, es de 8 bytes si se establece la marca EVENT_HEADER_FLAG_64_BIT_HEADER. La estructura EVENT_RECORD (evntcons.h) se pasa a la función de devolución de llamada [PEVENT_RECORD_CALLBACK].

[in] PropertyInType

Tipo de entrada de la propiedad . Use el miembro InType de la estructura EVENT_PROPERTY_INFO para establecer este parámetro.

[in] PropertyOutType

Tipo de salida de la propiedad . Use el miembro OutType de la estructura EVENT_PROPERTY_INFO para establecer este parámetro.

[in] PropertyLength

Longitud, en bytes, de la propiedad . Use el miembro Length de la estructura EVENT_PROPERTY_INFO para establecer este parámetro.

[in] UserDataLength

Tamaño, en bytes, del búfer UserData . Vea la sección Comentarios.

[in] UserData

Búfer que contiene los datos del evento. Vea la sección Comentarios.

[in, out] BufferSize

Tamaño, en bytes, del búfer de búfer . Si la función se ejecuta correctamente, este parámetro recibe el tamaño del búfer usado. Si el búfer es demasiado pequeño, la función devuelve ERROR_INSUFFICIENT_BUFFER y establece este parámetro en el tamaño de búfer necesario. Si el tamaño del búfer es cero en la entrada, no se devuelve ningún dato en el búfer y este parámetro recibe el tamaño de búfer necesario.

[out, optional] Buffer

Un búfer asignado por el autor de la llamada que contiene el valor de propiedad con formato. Para determinar el tamaño de búfer necesario, establezca este parámetro en NULL y BufferSize en cero.

[out] UserDataConsumed

Longitud, en bytes, de los datos de evento consumidos. Use este valor para ajustar los valores de los parámetros UserData y UserDataLength . Vea la sección Comentarios.

Valor devuelto

Devuelve ERROR_SUCCESS si se ejecuta correctamente. De lo contrario, esta función devuelve uno de los siguientes códigos de retorno además de otros.

Código devuelto Descripción
ERROR_INSUFFICIENT_BUFFER El tamaño del búfer de pBuffer es demasiado pequeño. Use el tamaño de búfer necesario establecido en pBufferSize para asignar un nuevo búfer.
ERROR_INVALID_PARAMETER Uno o varios de los parámetros no son válidos.
ERROR_EVT_INVALID_EVENT_DATA Los datos del evento no coinciden con la definición de evento en el manifiesto.

Comentarios

Normalmente, se llama a esta función en un bucle . Use el TRACE_EVENT_INFO. Miembro TopLevelPropertyCount para controlar el bucle (la función TdhGetEventInformation devuelve la estructura TRACE_EVENT_INFO). Antes de escribir el bucle, establezca los parámetros UserData y UserDataLength en el valor de los miembros UserData y UserDataLength de la estructura EVENT_RECORD, respectivamente. La estructura EVENT_RECORD se pasa a la función de devolución de llamada [PEVENT_RECORD_CALLBACK].

Determine si la propiedad es una matriz. La propiedad es una matriz si el EVENT_PROPERTY_INFO. El miembro Flags se establece en PropertyParamCount o el miembro EVENT_PROPERTY_INFO.count es mayor que 1. Llame a la función TdhFormatProperty en un bucle basado en el número de elementos de la matriz.

Después de llamar a la función TdhFormatProperty, use el valor del parámetro UserDataConsumed para establecer los nuevos valores de los parámetros UserData y UserDataLength (resta UserDataConsumed de UserDataLength y use UserDataLength para incrementar el puntero UserData).

Si la propiedad es una dirección IP V6, debe establecer el parámetro PropertyLength en el tamaño de la estructura IN6_ADDR . La propiedad se considera una dirección IP V6 si se cumplen las condiciones siguientes:

Ejemplos

Para ver un ejemplo que muestra cómo llamar a esta función, consulte Uso de TdhFormatProperty para consumir datos de eventos.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado tdh.h
Library Tdh.lib
Archivo DLL Tdh.dll