EvtFormatMessage-Funktion (winevt.h)

  • Artikel

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 zu den Metadaten des Anbieters, die die Funktion EvtOpenPublisherMetadata zurückgibt. Das Handle fungiert als Formatierungskontext für das Ereignis oder den 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 Ereigniseigenschaft, die Sie formatieren, in der datei Winmeta.xml definiert ist (z. B. wenn die Ebene auf "win:Error" festgelegt ist). Im letzten Fall verwendet der Dienst den Winmeta-Anbieter als Formatierungskontext und formatiert nur die Nachrichtenzeichenfolgen, auf die Sie in Ihrem Ereignis verweisen, das in der Winmeta.xml-Datei definiert ist.

[in] Event

Ein Handle zu einem Ereignis. Der Parameter Flags gibt die Nachrichtenzeichenfolge im Ereignis an, das Sie formatieren möchten. Dieser Parameter muss NULL sein, wenn der Parameter "Flags " auf "EvtFormatMessageId" festgelegt ist.

[in] MessageId

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

[in] ValueCount

Die Anzahl der Werte im Parameter "Values ".

[in] Values

Ein Array von Einfügewerten, die beim Formatieren der Nachrichtenzeichenfolge des Ereignisses verwendet werden sollen. In der Regel legen Sie diesen Parameter auf NULL fest, und die Funktion ruft die Einfügewerte aus den Ereignisdaten selbst ab. Mit diesem Parameter können Sie das Standardverhalten außer Kraft setzen und die zu verwendenden Einfügewerte angeben. Beispielsweise können Sie diesen Parameter verwenden, wenn Sie eine SID in einen Prinzipalnamen auflösen möchten, bevor Sie den Wert einfügen.

Um die Einfügewerte außer Kraft zu setzen, muss der Parameter "Flags " 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 aufrufergeteilter 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, der vom PublisherMetadata-Parameter angegeben ist. Nachdem die Nachrichten-ID gefunden wurde, werden die folgenden Suchalgorithmen verwendet.

Für Ereignisnachrichten:

  1. Durchsuchen Sie die datei, die im MessageFileName-Attribut des Anbieterelements angegeben ist.
  2. Falls nicht gefunden, suchen Sie Systemnachrichten.
Für die Attribute "Level", "Opcode" und "Keyword" des Ereigniselements :
  1. Durchsuchen Sie die Winmeta-Anbieterressourcen.
  2. Durchsuchen Sie die datei, die im MessageFileName-Attribut des Anbieterelements angegeben ist.
Für das Task-Attribut des Ereigniselements :
  1. Durchsuchen Sie die datei, die im MessageFileName-Attribut des Anbieterelements angegeben ist.
  2. Wenn sie nicht gefunden wurde, durchsuchen Sie die Winmeta-Anbieterressourcen.
Für lokalisierbare Parameter, auf die als %%n verwiesen wird (wobei n die Nachrichten-ID ist) in der Ereignismeldung:
  1. Suchdateien, die im ParameterFileName-Attribut des Anbieterelements von links nach rechts aufgeführt sind.
  2. Falls nicht gefunden, suchen Sie Systemnachrichten.

Beispiele

Ein Beispiel zur Verwendung dieser Funktion finden Sie unter Formatieren von Ereignisnachrichten und Abrufen der Metadaten eines Anbieters.

Anforderungen

   
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