Função TdhFormatProperty (tdh.h)

  • Artigo

Formata um valor de propriedade para exibição.

Sintaxe

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

Uma estrutura TRACE_EVENT_INFO que contém as informações do evento. Para obter essa estrutura, chame a função TdhGetEventInformation.

[in, optional] MapInfo

Uma estrutura EVENT_MAP_INFO que mapeia valores inteiros e bits para cadeias de caracteres. Para obter essa estrutura, chame a função TdhGetEventMapInformation. Para obter o nome do mapa, use o membro MapNameOffset da estrutura EVENT_PROPERTY_INFO. Se você não fornecer as informações do mapa para uma propriedade mapeada, a função formatará o valor inteiro ou bit.

[in] PointerSize

O tamanho de um valor de ponteiro nos dados do evento. Para obter o tamanho, acesse o EVENT_RECORD. Membro EventHeader.Flags . O tamanho do ponteiro será de 4 bytes se o sinalizador EVENT_HEADER_FLAG_32_BIT_HEADER estiver definido; caso contrário, serão 8 bytes se o sinalizador EVENT_HEADER_FLAG_64_BIT_HEADER estiver definido. A estrutura de EVENT_RECORD (evntcons.h) é passada para sua função de retorno de chamada [PEVENT_RECORD_CALLBACK].

[in] PropertyInType

O tipo de entrada da propriedade . Use o membro InType da estrutura EVENT_PROPERTY_INFO para definir esse parâmetro.

[in] PropertyOutType

O tipo de saída da propriedade . Use o membro OutType da estrutura EVENT_PROPERTY_INFO para definir esse parâmetro.

[in] PropertyLength

O comprimento, em bytes, da propriedade . Use o membro Length da estrutura EVENT_PROPERTY_INFO para definir esse parâmetro.

[in] UserDataLength

O tamanho, em bytes, do buffer UserData . Consulte Observações.

[in] UserData

O buffer que contém os dados do evento. Consulte Observações.

[in, out] BufferSize

O tamanho, em bytes , do buffer buffer. Se a função for bem-sucedida, esse parâmetro receberá o tamanho do buffer usado. Se o buffer for muito pequeno, a função retornará ERROR_INSUFFICIENT_BUFFER e definirá esse parâmetro para o tamanho do buffer necessário. Se o tamanho do buffer for zero na entrada, nenhum dado será retornado no buffer e esse parâmetro receberá o tamanho do buffer necessário.

[out, optional] Buffer

Um buffer alocado pelo chamador que contém o valor da propriedade formatada. Para determinar o tamanho do buffer necessário, defina esse parâmetro como NULL e BufferSize como zero.

[out] UserDataConsumed

O comprimento, em bytes, dos dados de evento consumidos. Use esse valor para ajustar os valores dos parâmetros UserData e UserDataLength . Consulte Observações.

Valor retornado

Retorna ERROR_SUCCESS se tiver êxito. Caso contrário, essa função retornará um dos seguintes códigos de retorno, além de outros.

Código de retorno Descrição
ERROR_INSUFFICIENT_BUFFER O tamanho do buffer pBuffer é muito pequeno. Use o conjunto de tamanho de buffer necessário no pBufferSize para alocar um novo buffer.
ERROR_INVALID_PARAMETER Um ou mais dos parâmetros não são válidos.
ERROR_EVT_INVALID_EVENT_DATA Os dados do evento não correspondem à definição de evento no manifesto.

Comentários

Normalmente, você chama essa função em um loop. Use o TRACE_EVENT_INFO. Membro TopLevelPropertyCount para controlar o loop (a função TdhGetEventInformation retorna a estrutura TRACE_EVENT_INFO). Antes de inserir o loop, defina os parâmetros UserData e UserDataLength como o valor dos membros UserData e UserDataLength da estrutura EVENT_RECORD, respectivamente. A estrutura EVENT_RECORD é passada para sua função de retorno de chamada [PEVENT_RECORD_CALLBACK].

Determine se a propriedade é uma matriz. A propriedade será uma matriz se o EVENT_PROPERTY_INFO. O membro Flags é definido como PropertyParamCount ou o membro EVENT_PROPERTY_INFO.count é maior que 1. Chame a função TdhFormatProperty em um loop com base no número de elementos na matriz.

Depois de chamar a função TdhFormatProperty , use o valor do parâmetro UserDataConsumed para definir os novos valores dos parâmetros UserData e UserDataLength (Subtrair UserDataConsumed de UserDataLength e usar UserDataLength para incrementar o ponteiro UserData ).

Se a propriedade for um endereço IP V6, você deverá definir o parâmetro PropertyLength para o tamanho da estrutura IN6_ADDR . A propriedade será considerada um endereço IP V6 se as seguintes condições forem atendidas:

Exemplos

Para obter um exemplo que mostra como chamar essa função , consulte Usando TdhFormatProperty para consumir dados de evento.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho tdh.h
Biblioteca Tdh.lib
DLL Tdh.dll