FormatMessage(A)

メッセージ文字列を書式化します。入力としてメッセージ定義を使用し、要求に応じて挿入句を埋め込んでから、書式化されたメッセージテキストをバッファに出力します。メッセージ定義は、関数の引数として渡すことができます。ロードされたモジュール内のメッセージテーブルリソースを使用するよう指示することもできます。 Windows システムが持っているメッセージテーブルリソースを使用するよう指示することもできます。

DWORD FormatMessageA(
    DWORD   dwFlags,       // 動作フラグ
    PCVOID  pSource,       // メッセージ定義位置
    DWORD   dwMessageID,   // メッセージID
    DWORD   dwLanguageID,  // 言語ID
    PTSTR   pszBuffer,     // バッファのアドレス
    DWORD   nSize,         // バッファのサイズ
    va_list *Arguments     // 挿入句の配列のアドレス
);

KERNEL32.DLL

引数

dwFlags

書式化処理の方法や pSource パラメータの解釈を指定します。以下の値の組み合わせで指定します

値	意味
0x00000100 (FORMAT_MESSAGE_ALLOCATE_BUFFER)
	FormatMessage 関数に、バッファの割り当てを要求します。このフラグを指定した場合は、 pszBuffer パラメータに変数のアドレスを、 nSize パラメータに出力メッセージバッファに割り当てるバイト数の最小値を指定してください。 FormatMessage 関数は、書式化済みのメッセージを格納しておくのに十分なサイズのバッファを自動的に割り当て、そのバッファのアドレスを pszBuffer で指定された変数に格納します。このバッファが不要になったら、 LocalFree 関数を使ってバッファを解放してください。 このフラグを指定しなかった場合は、アプリケーション側でバッファを用意しなければなりません。
0x00000200 (FORMAT_MESSAGE_IGNORE_INSERTS)
	Arguments パラメータを無視するよう要求します。埋め込み挿入句は埋め込まれず、メッセージ定義がそのままバッファに出力されます。
0x00000400 (FORMAT_MESSAGE_FROM_STRING)
	メッセージ定義として、 pSource パラメータで指定した NULL で終わる文字列を使用するよう要求します。 FORMAT_MESSAGE_FROM_HMODULE フラグや FORMAT_MESSAGE_FROM_SYSTEM フラグと同時に指定することはできません。
0x00000800 (FORMAT_MESSAGE_FROM_HMODULE)
	メッセージ定義として、モジュール内のメッセージ定義リソースを使用するよう要求します。このフラグを指定した場合は、 pSource パラメータにモジュールのハンドルを指定してください。 pSource パラメータに 0 (NULL) を指定すると、現在のプロセスのモジュールが指定されたものとみなされます。 FORMAT_MESSAGE_FROM_STRING フラグと同時に指定することはできません。
0x00001000 (FORMAT_MESSAGE_FROM_SYSTEM)
	メッセージ定義として、システムメッセージテーブルリソースを使用するよう要求します。このフラグは、 GetLastError 関数で取得したエラーコードをメッセージテキストに変換する際に役立ちます。 FORMAT_MESSAGE_FROM_HMODULE フラグと同時に指定した場合は、FORMAT_MESSAGE_FROM_HMODULE フラグが優先されます。しかし、モジュール内にメッセージ定義リソースが見つからなかった場合は、システムメッセージテーブルリソースが使われます。
0x00002000 (FORMAT_MESSAGE_ARGUMENT_ARRAY)
	Arguments パラメータに、 va_list 構造体ではなく、32ビット値の配列へのポインタを指定した場合に、このフラグを指定します。

pSource

メッセージ定義の位置を指定します。

dwFlags パラメータで FORMAT_MESSAGE_FROM_HMODULE フラグを指定した場合は、メッセージ定義リソースを含むモジュールのハンドルを指定します。

dwFlags パラメータで FORMAT_MESSAGE_FROM_STRING フラグを指定した場合は、NULLで終わる文字列へのポインタを指定します。

dwFlags パラメータで、前記の2つのフラグのどちらも指定されていなかった場合、このパラメータは無視されます。

dwMessageID

32ビットのメッセージ ID を指定します。 dwFlags パラメータで FORMAT_MESSAGE_FROM_STRING フラグを指定した場合は、このパラメータは無視されます。

dwLanguageID

32ビットの言語 ID を指定します。 FormatMessage 関数は、指定された言語 ID と一致するメッセージを使用します。指定された言語 ID と一致するメッセージが見つからなかった場合は、戻り値として 1815 (ERROR_RESOURCE_LANG_NOT_FOUND) を返します。

0 を指定すると、内部のルールに基づいて言語 ID が決定されます。

dwFlags パラメータで FORMAT_MESSAGE_FROM_STRING フラグを指定した場合は、このパラメータは無視されます。

pszBuffer

dwFlags パラメータで FORMAT_MESSAGE_ALLOCATE_BUFFER フラグを指定しなかった場合は、バッファへのポインタを指定します。このバッファに、書式化されたメッセージが、 NULL で終わる文字列として格納されます。

dwFlags パラメータで FORMAT_MESSAGE_ALLOCATE_BUFFER フラグを指定した場合は、 PVOID 型変数のアドレスを指定します。この関数は、 LocalAlloc 関数を使ってバッファを自動的に確保し、そのバッファへのポインタを pszBuffer パラメータで指定したアドレスに格納します。

nSize

dwFlags パラメータで FORMAT_MESSAGE_ALLOCATE_BUFFER フラグを指定しなかった場合は、pszBuffer バッファのサイズをバイト数（Unicode 版の場合は文字数）で指定します。

dwFlags パラメータで FORMAT_MESSAGE_ALLOCATE_BUFFER フラグを指定した場合は、FormatMessage 関数に割り当てさせるバッファの最小サイズを、バイト数（Unicode 版の場合は文字数）で指定します。

Arguments

挿入句を、32ビット値の配列へのポインタとして指定します。配列の最初の要素が書式文字列中の %1 に、次の要素が %2 に、その次の要素が %3 に対応します。以下同様です。配列の各要素の解釈は、対応する %n の指示によって異なりますが、デフォルトでは NULL で終わる文字列へのポインタとして扱われます。

Windows 95/98/Me： 1つの挿入文字列が1,023文字を超えてはいけません。

戻り値

関数が成功すると、バッファに格納されたバイト数（Unicode 版の場合は文字数）が返ります（終端のNULLを文字除く）。

関数が失敗すると 0 が返ります。拡張エラー情報を取得するには、 GetLastError 関数を使います。

解説

メッセージ定義には、書式化のための書式指定子を含めることができます。書式指定子の例を次に示します。

対応情報

Windows 95 以降 / Windows NT 3.1 以降