Função EvtFormatMessage (winevt.h)

  • Artigo

Formata uma cadeia de caracteres de mensagem.

Sintaxe

BOOL EvtFormatMessage(
  [in]  EVT_HANDLE   PublisherMetadata,
  [in]  EVT_HANDLE   Event,
  [in]  DWORD        MessageId,
  [in]  DWORD        ValueCount,
  [in]  PEVT_VARIANT Values,
  [in]  DWORD        Flags,
  [in]  DWORD        BufferSize,
  [in]  LPWSTR       Buffer,
  [out] PDWORD       BufferUsed
);

Parâmetros

[in] PublisherMetadata

Um identificador para os metadados do provedor que a função EvtOpenPublisherMetadata retorna. O identificador atua como um contexto de formatação para o evento ou identificador de mensagem.

Você pode definir esse parâmetro como NULL se o serviço Coletor de Eventos do Windows encaminhou o evento. Os eventos encaminhados incluem uma seção RenderingInfo que contém as cadeias de caracteres de mensagem renderizadas. Você também poderá definir esse parâmetro como NULL se a propriedade de evento que você está formata estiver definida no arquivo Winmeta.xml (por exemplo, se level estiver definido como win:Error). No último caso, o serviço usa o provedor Winmeta como o contexto de formatação e formatará apenas as cadeias de caracteres de mensagem que você referencia no evento definido no arquivo Winmeta.xml.

[in] Event

Um identificador para um evento. O parâmetro Flags especifica a cadeia de caracteres de mensagem no evento que você deseja formatar. Esse parâmetro deverá ser NULL se o parâmetro Flags estiver definido como EvtFormatMessageId.

[in] MessageId

O identificador de recurso da cadeia de caracteres de mensagem que você deseja formatar. Para obter o identificador de recurso de uma cadeia de caracteres de mensagem, chame a função GetPublisherMetadataProperty . Defina esse parâmetro somente se o parâmetro Flags estiver definido como EvtFormatMessageId.

[in] ValueCount

O número de valores no parâmetro Values .

[in] Values

Uma matriz de valores de inserção a ser usada ao formatar a cadeia de caracteres de mensagem do evento. Normalmente, você define esse parâmetro como NULL e a função obtém os valores de inserção dos próprios dados de evento. Você usaria esse parâmetro para substituir o comportamento padrão e fornecer os valores de inserção a serem usados. Por exemplo, você pode usar esse parâmetro se quiser resolve um SID para um nome principal antes de inserir o valor.

Para substituir os valores de inserção, o parâmetro Flags deve ser definido como EvtFormatMessageEvent, EvtFormatMessageXML ou EvtFormatMessageId. Se Flags estiver definido como EvtFormatMessageId, o identificador de recurso deverá identificar a cadeia de caracteres de mensagem do evento.

[in] Flags

Um sinalizador que especifica a cadeia de caracteres de mensagem no evento a ser formatado. Para obter os valores possíveis, consulte a enumeração EVT_FORMAT_MESSAGE_FLAGS .

[in] BufferSize

O tamanho do buffer de buffer, em caracteres.

[in] Buffer

Um buffer alocado pelo chamador que receberá a cadeia de caracteres de mensagem formatada. Você pode definir esse parâmetro como NULL para determinar o tamanho do buffer necessário.

[out] BufferUsed

O tamanho, em caracteres do buffer alocado pelo chamador que a função usou ou o tamanho do buffer necessário se a função falhar com ERROR_INSUFFICIENT_BUFFER.

Retornar valor

Valor/código retornado Descrição
TRUE
 A função foi bem-sucedida.
FALSE
 A função falhou. Chame a função GetLastError para obter o código de erro.

Comentários

Quando o serviço tenta localizar uma mensagem para um evento, o serviço examina os recursos da tabela de mensagens do publicador indicados pelo parâmetro PublisherMetadata . Depois que a ID da mensagem for encontrada, os algoritmos de pesquisa a seguir serão usados.

Para mensagens de evento:

  1. Pesquise o arquivo especificado no atributo messageFileName do elemento do provedor .
  2. Se não for encontrado, pesquise mensagens do sistema.
Para os atributos Level, Opcode e Keyword do elemento event :
  1. Pesquise os recursos do provedor winmeta.
  2. Pesquise o arquivo especificado no atributo messageFileName do elemento do provedor .
Para o atributo Task do elemento event :
  1. Pesquise o arquivo especificado no atributo messageFileName do elemento do provedor .
  2. Se não for encontrado, pesquise os recursos do provedor winmeta.
Para parâmetros localizáveis referenciados como %%n (em que n é a ID da mensagem) na mensagem de evento:
  1. Pesquisar arquivos listados no atributo parameterFileName do elemento do provedor da esquerda para a direita.
  2. Se não for encontrado, pesquise mensagens do sistema.

Exemplos

Para obter um exemplo que mostra como usar essa função, consulte Formatar mensagens de evento e Obter metadados de um provedor.

Requisitos

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

Confira também

FormatMessage