メッセージ文字列を書式化します。入力としてメッセージ定義を使用し、要求に応じて挿入句を埋め込んでから、書式化されたメッセージテキストをバッファに出力します。メッセージ定義は、関数の引数として渡すことができます。ロードされたモジュール内のメッセージテーブルリソースを使用するよう指示することもできます。 Windows システムが持っているメッセージテーブルリソースを使用するよう指示することもできます。
DWORD FormatMessageA(
DWORD dwFlags,
PCVOID pSource,
DWORD dwMessageID,
DWORD dwLanguageID,
PTSTR pszBuffer,
DWORD nSize,
va_list *Arguments
);
KERNEL32.DLL
書式化処理の方法やpSourceパラメータの解釈を指定します。以下の値の組み合わせで指定します
FormatMessage関数に、バッファの割り当てを要求します。このフラグを指定した場合は、pszBufferパラメータに変数のアドレスを、nSizeパラメータに出力メッセージバッファに割り当てるバイト数の最小値を指定してください。
FormatMessage関数は、書式化済みのメッセージを格納しておくのに十分なサイズのバッファを自動的に割り当て、そのバッファのアドレスをpszBufferで指定された変数に格納します。このバッファが不要になったら、LocalFree関数を使ってバッファを解放してください。
このフラグを指定しなかった場合は、アプリケーション側でバッファを用意しなければなりません。
Argumentsパラメータを無視するよう要求します。埋め込み挿入句は埋め込まれず、メッセージ定義がそのままバッファに出力されます。
メッセージ定義として、pSourceパラメータで指定したヌル終端文字列を使用するよう要求します。FORMAT_MESSAGE_FROM_HMODULEフラグやFORMAT_MESSAGE_FROM_SYSTEMフラグと同時に指定することはできません。
メッセージ定義として、モジュール内のメッセージ定義リソースを使用するよう要求します。このフラグを指定した場合は、pSourceパラメータにモジュールのハンドルを指定してください。pSourceパラメータに0 (NULL) を指定すると、現在のプロセスのモジュールが指定されたものとみなされます。FORMAT_MESSAGE_FROM_STRINGフラグと同時に指定することはできません。
メッセージ定義として、システムメッセージテーブルリソースを使用するよう要求します。このフラグは、GetLastError関数で取得したエラーコードをメッセージテキストに変換する際に役立ちます。
FORMAT_MESSAGE_FROM_HMODULEフラグと同時に指定した場合は、FORMAT_MESSAGE_FROM_HMODULEフラグが優先されます。しかし、モジュール内にメッセージ定義リソースが見つからなかった場合は、システムメッセージテーブルリソースが使われます。
Argumentsパラメータに、va_list 構造体ではなく、32ビット値の配列へのポインタを指定した場合に、このフラグを指定します。
メッセージ定義の位置を指定します。
dwFlagsパラメータでFORMAT_MESSAGE_FROM_HMODULEフラグを指定した場合は、メッセージ定義リソースを含むモジュールのハンドルを指定します。
dwFlagsパラメータでFORMAT_MESSAGE_FROM_STRINGフラグを指定した場合は、ヌル終端文字列へのポインタを指定します。
dwFlagsパラメータで、前記の2つのフラグのどちらも指定されていなかった場合、このパラメータは無視されます。
32ビットのメッセージIDを指定します。dwFlagsパラメータでFORMAT_MESSAGE_FROM_STRINGフラグを指定した場合は、このパラメータは無視されます。
32ビットの言語IDを指定します。FormatMessage関数は、指定された言語IDと一致するメッセージを使用します。指定された言語IDと一致するメッセージが見つからなかった場合は、戻り値として1815 (ERROR_RESOURCE_LANG_NOT_FOUND) を返します。
0を指定すると、内部のルールに基づいて言語IDが決定されます。
dwFlagsパラメータでFORMAT_MESSAGE_FROM_STRINGフラグを指定した場合は、このパラメータは無視されます。
dwFlagsパラメータでFORMAT_MESSAGE_ALLOCATE_BUFFERフラグを指定しなかった場合は、バッファへのポインタを指定します。このバッファに、書式化されたメッセージが、ヌル終端文字列として格納されます。
dwFlagsパラメータでFORMAT_MESSAGE_ALLOCATE_BUFFERフラグを指定した場合は、PVOID型変数のアドレスを指定します。この関数は、LocalAlloc関数を使ってバッファを自動的に確保し、そのバッファへのポインタをpszBufferパラメータで指定したアドレスに格納します。
dwFlagsパラメータでFORMAT_MESSAGE_ALLOCATE_BUFFERフラグを指定しなかった場合は、pszBufferバッファのサイズをバイト数（Unicode版の場合は文字数）で指定します。
dwFlagsパラメータでFORMAT_MESSAGE_ALLOCATE_BUFFERフラグを指定した場合は、FormatMessage関数に割り当てさせるバッファの最小サイズを、バイト数（Unicode版の場合は文字数）で指定します。
挿入句を、32ビット値の配列へのポインタとして指定します。配列の最初の要素が書式文字列中の %1 に、次の要素が %2 に、その次の要素が %3 に対応します。以下同様です。配列の各要素の解釈は、対応する %n の指示によって異なりますが、デフォルトではヌル終端文字列へのポインタとして扱われます。
Windows 95/98/Me： 1つの挿入文字列が1,023文字を超えてはいけません。
関数が成功すると、バッファに格納されたバイト数（Unicode版の場合は文字数）が返ります（終端ヌル文字を除く）。
関数が失敗すると0が返ります。拡張エラー情報を取得するには、GetLastError関数を使います。
メッセージ定義には、書式化のための書式指定子を含めることができます。書式指定子の例を次に示します。
| 書式指定子 | 意味 |
|---|---|
| %数値!書式指定子! |
挿入句の埋め込み場所を指示します。 「%数値」には、%の後に1以上99以下の数字を指定します。「%1」がArgumentsパラメータで指定した配列の最初の要素に、「%2」が次の要素に対応します。以下同様です。 「!書式指定子!」には、wsprintf 関数で使う書式指定子（「!s!」や「!d!」など）を指定します。ただし、「!e!」「!E!」「!f!」「!g!」は使えません。「!書式指定子!」を指定しなかった場合は、「!s!」が指定されたものとみなされます。 |
| %% | パーセント記号（%） |
| %n | 改行 |
Windows 95 以降 / Windows NT 3.1 以降