EvtFormatMessage-Funktion (winevt.h)

Artikel
03/04/2024

Formatiert eine Nachrichtenzeichenfolge.

Syntax

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

Parameter

[in] PublisherMetadata

Ein Handle für die Metadaten des Anbieters, die von der EvtOpenPublisherMetadata-Funktion zurückgegeben werden . Das Handle fungiert als Formatierungskontext für den Ereignis- oder Nachrichtenbezeichner.

Sie können diesen Parameter auf NULL festlegen, wenn der Windows-Ereignissammlerdienst das Ereignis weitergeleitet hat. Weitergeleitete Ereignisse enthalten einen RenderingInfo-Abschnitt , der die gerenderten Nachrichtenzeichenfolgen enthält. Sie können diesen Parameter auch auf NULL festlegen, wenn die von Ihnen formatierte Ereigniseigenschaft in der Winmeta.xml-Datei definiert ist (z. B. wenn level auf win:Error festgelegt ist). Im letzteren Fall verwendet der Dienst den Winmeta-Anbieter als Formatierungskontext und formatiert nur die Nachrichtenzeichenfolgen, auf die Sie in Ihrem Ereignis verweisen, die in der Winmeta.xml-Datei definiert sind.

[in] Event

Ein Handle für ein Ereignis. Der Parameter Flags gibt die Meldungszeichenfolge in dem Ereignis an, das Sie formatieren möchten. Dieser Parameter muss NULL sein, wenn der Flags-Parameter auf EvtFormatMessageId festgelegt ist.

[in] MessageId

Der Ressourcenbezeichner der Nachrichtenzeichenfolge, die Sie formatieren möchten. Um den Ressourcenbezeichner für eine Nachrichtenzeichenfolge abzurufen, rufen Sie die GetPublisherMetadataProperty-Funktion auf. Legen Sie diesen Parameter nur fest, wenn der Flags-Parameter auf EvtFormatMessageId festgelegt ist.

[in] ValueCount

Die Anzahl der Werte im Values-Parameter .

[in] Values

Ein Array von Einfügewerten, das beim Formatieren der Nachrichtenzeichenfolge des Ereignisses verwendet werden soll. In der Regel legen Sie diesen Parameter auf NULL fest, und die Funktion ruft die Einfügewerte aus den Ereignisdaten selbst ab. Sie würden diesen Parameter verwenden, um das Standardverhalten zu überschreiben und die zu verwendenden Einfügewerte anzugeben. Beispielsweise können Sie diesen Parameter verwenden, wenn Sie eine SID vor dem Einfügen des Werts in einen Prinzipalnamen auflösen möchten.

Um die Einfügewerte außer Kraft zu setzen, muss der Flags-Parameter auf EvtFormatMessageEvent, EvtFormatMessageXML oder EvtFormatMessageId festgelegt werden. Wenn Flags auf EvtFormatMessageId festgelegt ist, muss der Ressourcenbezeichner die Nachrichtenzeichenfolge des Ereignisses identifizieren.

[in] Flags

Ein Flag, das die Nachrichtenzeichenfolge im zu formatierenden Ereignis angibt. Mögliche Werte finden Sie in der EVT_FORMAT_MESSAGE_FLAGS-Enumeration .

[in] BufferSize

Die Größe des Pufferpuffers in Zeichen.

[in] Buffer

Ein vom Aufrufer zugewiesener Puffer, der die formatierte Nachrichtenzeichenfolge empfängt. Sie können diesen Parameter auf NULL festlegen, um die erforderliche Puffergröße zu bestimmen.

[out] BufferUsed

Die Größe in Zeichen des vom Aufrufer zugewiesenen Puffers, den die Funktion verwendet hat, oder die erforderliche Puffergröße, wenn die Funktion mit ERROR_INSUFFICIENT_BUFFER fehlschlägt.

Rückgabewert

Rückgabecode/-wert	BESCHREIBUNG
TRUE	Die Funktion wurde erfolgreich ausgeführt.
FALSE	Fehler bei der Funktion. Rufen Sie die GetLastError-Funktion auf, um den Fehlercode abzurufen.

Hinweise

Wenn der Dienst versucht, eine Nachricht für ein Ereignis zu finden, sucht der Dienst in den Nachrichtentabellenressourcen des Herausgebers, die durch den PublisherMetadata-Parameter angegeben werden. Nachdem die Nachrichten-ID gefunden wurde, werden die folgenden Suchalgorithmen verwendet.

Für Ereignismeldungen:

Durchsuchen Sie die datei, die im messageFileName-Attribut des provider-Elements angegeben ist.
Wenn sie nicht gefunden werden, werden Systemnachrichten gesucht.

Für die Attribute Level, Opcode und Keyword des Ereigniselements :

Durchsuchen Sie die Winmeta-Anbieterressourcen.
Durchsuchen Sie die datei, die im messageFileName-Attribut des provider-Elements angegeben ist.

Für das Task-Attribut des Ereigniselements :

Durchsuchen Sie die datei, die im messageFileName-Attribut des provider-Elements angegeben ist.
Wenn sie nicht gefunden werden, suchen Sie die Winmeta-Anbieterressourcen.

Für lokalisierbare Parameter, auf die in der Ereignisnachricht als %%n verwiesen wird (wobei n die Nachrichten-ID ist):

Suchen Sie Dateien, die im ParameterFileName-Attribut des Anbieterelements von links nach rechts aufgeführt sind.
Wenn sie nicht gefunden werden, werden Systemnachrichten gesucht.

Beispiele

Ein Beispiel für die Verwendung dieser Funktion finden Sie unter Formatieren von Ereignismeldungen und Abrufen der Metadaten eines Anbieters.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winevt.h
Bibliothek	Wevtapi.lib
DLL	Wevtapi.dll

Weitere Informationen

FormatMessage

Freigeben über