Funzione EvtFormatMessage (winevt.h)

Articolo
08/27/2023

Formatta una stringa di messaggio.

Sintassi

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
);

Parametri

[in] PublisherMetadata

Handle per i metadati del provider restituiti dalla funzione EvtOpenPublisherMetadata . L'handle funge da contesto di formattazione per l'evento o l'identificatore del messaggio.

È possibile impostare questo parametro su NULL se il servizio Agente di raccolta eventi di Windows ha inoltrato l'evento. Gli eventi inoltrati includono una sezione RenderingInfo contenente le stringhe di messaggio di cui è stato eseguito il rendering. È anche possibile impostare questo parametro su NULL se la proprietà dell'evento che si sta formattando è definita nel file Winmeta.xml (ad esempio, se level è impostato su win:Error). Nel secondo caso, il servizio usa il provider Winmeta come contesto di formattazione e formatta solo le stringhe di messaggio a cui si fa riferimento nell'evento definito nel file Winmeta.xml.

[in] Event

Handle per un evento. Il parametro Flags specifica la stringa di messaggio nell'evento che si desidera formattare. Questo parametro deve essere NULL se il parametro Flags è impostato su EvtFormatMessageId.

[in] MessageId

Identificatore della risorsa della stringa di messaggio da formattare. Per ottenere l'identificatore di risorsa per una stringa di messaggio, chiamare la funzione GetPublisherMetadataProperty . Impostare questo parametro solo se il parametro Flags è impostato su EvtFormatMessageId.

[in] ValueCount

Numero di valori nel parametro Values .

[in] Values

Matrice di valori di inserimento da utilizzare durante la formattazione della stringa del messaggio dell'evento. In genere, questo parametro viene impostato su NULL e la funzione ottiene i valori di inserimento dai dati dell'evento stesso. Usare questo parametro per eseguire l'override del comportamento predefinito e specificare i valori di inserimento da usare. Ad esempio, è possibile usare questo parametro se si vuole risolvere un SID in un nome di entità prima di inserire il valore.

Per eseguire l'override dei valori di inserimento, il parametro Flags deve essere impostato su EvtFormatMessageEvent, EvtFormatMessageXML o EvtFormatMessageId. Se Flags è impostato su EvtFormatMessageId, l'identificatore della risorsa deve identificare la stringa del messaggio dell'evento.

[in] Flags

Flag che specifica la stringa del messaggio nell'evento da formattare. Per i valori possibili, vedere l'enumerazione EVT_FORMAT_MESSAGE_FLAGS .

[in] BufferSize

Dimensioni del buffer buffer , in caratteri.

[in] Buffer

Buffer allocato dal chiamante che riceverà la stringa del messaggio formattata. È possibile impostare questo parametro su NULL per determinare le dimensioni del buffer necessarie.

[out] BufferUsed

Dimensione, in caratteri del buffer allocato dal chiamante usato dalla funzione o dalla dimensione del buffer necessaria se la funzione ha esito negativo con ERROR_INSUFFICIENT_BUFFER.

Valore restituito

Codice/valore restituito	Descrizione
TRUE	Funzione completata.
FALSE	La funzione non è riuscita. Chiamare la funzione GetLastError per ottenere il codice di errore.

Commenti

Quando il servizio tenta di trovare un messaggio per un evento, il servizio cerca le risorse della tabella dei messaggi del server di pubblicazione indicate dal parametro PublisherMetadata . Dopo aver trovato l'ID del messaggio, vengono usati gli algoritmi di ricerca seguenti.

Per i messaggi di evento:

Cercare il file specificato nell'attributo messageFileName dell'elemento provider .
Se non viene trovato, cercare i messaggi di sistema.

Per gli attributi Level, Opcode e Keyword dell'elemento event :

Cercare le risorse del provider Winmeta.
Cercare il file specificato nell'attributo messageFileName dell'elemento provider .

Per l'attributo Task dell'elemento evento :

Cercare il file specificato nell'attributo messageFileName dell'elemento provider .
Se non viene trovato, cercare le risorse del provider Winmeta.

Per i parametri localizzabili a cui si fa riferimento come %%n (dove n è l'ID messaggio) nel messaggio dell'evento:

Cercare i file elencati nell'attributo parameterFileName dell'elemento provider da sinistra a destra.
Se non viene trovato, cercare i messaggi di sistema.

Esempio

Per un esempio che illustra come usare questa funzione, vedere Formattazione dei messaggi di evento e Recupero dei metadati di un provider.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winevt.h
Libreria	Wevtapi.lib
DLL	Wevtapi.dll

Vedi anche

FormatMessage

Condividi tramite