EvtFormatMessage 関数 (winevt.h)

  • [アーティクル]

メッセージ文字列を書式設定します。

構文

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

パラメーター

[in] PublisherMetadata

EvtOpenPublisherMetadata 関数が返すプロバイダーのメタデータへのハンドル。 ハンドルは、イベントまたはメッセージ識別子の書式設定コンテキストとして機能します。

Windows イベント コレクター サービスがイベントを転送した場合、このパラメーターを NULL に設定できます。 転送されるイベントには、レンダリングされたメッセージ文字列を含む RenderingInfo セクションが含まれます。 書式設定するイベント プロパティが Winmeta.xml ファイルで定義されている場合 (たとえば、level が win:Error に設定されている場合)、このパラメーターを NULL に設定することもできます。 後者の場合、サービスは Winmeta プロバイダーを書式設定コンテキストとして使用し、Winmeta.xml ファイルで定義されているイベントで参照するメッセージ文字列のみを書式設定します。

[in] Event

イベントへのハンドル。 Flags パラメーターは、書式設定するイベントのメッセージ文字列を指定します。 Flags パラメーターが EvtFormatMessageId に設定されている場合、このパラメーターは NULL である必要があります。

[in] MessageId

書式設定するメッセージ文字列のリソース識別子。 メッセージ文字列のリソース識別子を取得するには、 GetPublisherMetadataProperty 関数を呼び出します。 Flags パラメーターが EvtFormatMessageId に設定されている場合にのみ、このパラメーターを設定します。

[in] ValueCount

Values パラメーターの値の数。

[in] Values

イベントのメッセージ文字列を書式設定するときに使用する挿入値の配列。 通常、このパラメーターを NULL に設定すると、関数はイベント データ自体から挿入値を取得します。 このパラメーターを使用して、既定の動作をオーバーライドし、使用する挿入値を指定します。 たとえば、値を挿入する前に SID をプリンシパル名に解決する場合は、このパラメーターを使用できます。

挿入値をオーバーライドするには、Flags パラメーターを EvtFormatMessageEvent、EvtFormatMessageXML、または EvtFormatMessageId に設定する必要があります。 Flags が EvtFormatMessageId に設定されている場合、リソース識別子はイベントのメッセージ文字列を識別する必要があります。

[in] Flags

書式設定するイベントのメッセージ文字列を指定するフラグ。 使用可能な値については、 EVT_FORMAT_MESSAGE_FLAGS 列挙を参照してください。

[in] BufferSize

バッファー バッファーのサイズ (文字単位)。

[in] Buffer

書式設定されたメッセージ文字列を受け取る呼び出し元によって割り当てられたバッファー。 このパラメーターを NULL に設定して、必要なバッファー サイズを決定できます。

[out] BufferUsed

関数が使用した呼び出し元によって割り当てられたバッファーの文字単位のサイズ。関数がERROR_INSUFFICIENT_BUFFERで失敗した場合は、必要なバッファー サイズ。

戻り値

リターン コード/値 説明
TRUE
 関数が正常に実行されました。
FALSE
 関数が失敗しました。 エラー コードを取得するには、 GetLastError 関数を呼び出します。

注釈

サービスがイベントのメッセージを検索しようとすると、サービスは PublisherMetadata パラメーターによって示される発行元のメッセージ テーブル リソースを検索します。 メッセージ ID が見つかると、次の検索アルゴリズムが使用されます。

イベント メッセージの場合:

  1. provider 要素の messageFileName 属性で指定されたファイルを検索します。
  2. 見つからない場合は、システム メッセージを検索します。
イベント要素の Level、Opcode、Keyword 属性の場合:
  1. Winmeta プロバイダー リソースを検索します。
  2. provider 要素の messageFileName 属性で指定されたファイルを検索します。
イベント要素の Task 属性の場合:
  1. provider 要素の messageFileName 属性で指定されたファイルを検索します。
  2. 見つからない場合は、Winmeta プロバイダー リソースを検索します。
イベント メッセージで %%n ( n はメッセージ ID) として参照されるローカライズ可能なパラメーターの場合:
  1. provider 要素の parameterFileName 属性にリストされているファイルを左から右に検索します。
  2. 見つからない場合は、システム メッセージを検索します。

例

この関数の使用方法を示す例については、「 イベント メッセージの書式設定 」および「 プロバイダーのメタデータの取得」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winevt.h
Library Wevtapi.lib
[DLL] Wevtapi.dll

こちらもご覧ください

FormatMessage