API 関数解説

FormatMessage

Declare Function Api_FormatMessage& Lib "kernel32" Alias "FormatMessageA" (ByVal dwFlags&, lpSource As Any, ByVal dwMessageId&, ByVal dwLanguageId&, ByVal lpBuffer$, ByVal nSize&, Arguments&)

Declare Function FormatMessage Lib "kernel32" Alias "FormatMessageA" (ByVal dwFlags As Long, lpSource As Any, ByVal dwMessageId As Long, ByVal dwLanguageId As Long, ByVal lpBuffer As String, ByVal nSize As Long, Arguments As Long) As Long

メッセージ文字列を書式化する（書式を割り当てる）。この関数は、入力としてメッセージ定義を受け取る。メッセージ定義は、この関数に渡すバッファ経由で渡すことができる。代わりに、ロード済みのモジュール内のメッセージテーブルリソースを使うよう指示することもできる。または、システムのメッセージテーブルリソースからメッセージ定義を検索するよう指示することもできる。この関数は、メッセージ識別子と言語識別子に基づいて、メッセージテーブルリソース内のメッセージ定義を検索する。要求に応じて、埋め込まれた挿入シーケンスを処理し、書式化されたメッセージテキストを出力バッファへコピーする。

パラメータ
dwFlags
書式化処理の方法や、lpSource パラメータの解釈方法を指定する。

dwFlags の下位バイト（low-order byte）は、この関数がメッセージ定義テキスト内の改行記号を出力バッファへ反映する方法

（2 番目の表）を指定する。また、下位バイトで、書式化後の出力行の最大幅を指定することもできる。
次のフラグの任意の組み合わせを指定する。

値	意味
FORMAT_MESSAGE_ALLOCATE_BUFFER	FormatMessage 関数に、バッファの割り当てを要求する。このフラグを指定した場合
	は、lpBuffer パラメータで PVOID 型変数へのポインタを、nSize パラメータで出力メッセ
	ージバッファに割り当てる最小値を TCHAR 単位で指定する。
	FormatMessage 関数は、書式化済みのメッセージを格納するのに十分なサイズのバッ
	ファを自動的に割り当て、そのバッファへのポインタを、lpBuffer で指定されたアドレスに
	格納する。呼び出し側は、このバッファが不要になったら、LocalFree 関数を使ってバ
	ッファを解放するべきである。
FORMAT_MESSAGE_IGNORE_INSERTS	メッセージ定義の中の挿入シーケンスを無視して、何も変更を加えずに出力バッファへ渡
	すよう要求する。後で書式化を行うために、メッセージの取り出しを行う場合に役立ち
	ます。このフラグをセットすると、Arguments パラメータは無視される。
FORMAT_MESSAGE_FROM_STRING	lpSource パラメータが、NULL で終わるメッセージ定義へのポインタであると指定する。
	メッセージテーブルリソース内のメッセージテキストと同様、このメッセージ定義が、挿入シ
	ーケンスを含んでいてもかまわない。FORMAT_MESSAGE_FROM_HMODULE や
	FORMAT_MESSAGE_FROM_SYSTEM の各フラグと同時に指定することはできない。
FORMAT_MESSAGE_FROM_HMODULE	lpSource が、検索対象のメッセージテーブルリソースを保持しているモジュールのハンド
	ルであると指定する。lpSource パラメータに NULL を指定すると、現在のプロセスで動
	作しているアプリケーションのイメージファイルを検索対象にする。
	FORMAT_MESSAGE_FROM_STRING フラグと同時に指定することはできない。
FORMAT_MESSAGE_FROM_SYSTEM	要求されたメッセージを、システムメッセージテーブルリソースから検索するよう指定する。
	FORMAT_MESSAGE_FROM_HMODULE フラグと同時に指定した場合は、
	lpSource で指定されたモジュール内にメッセージが見つからないと、システムメッセージ
	テーブル内で検索を行う。
	このフラグを指定すると、アプリケーションは GetLastError 関数の結果を
	FormatMessage 関数に渡して、システム定義のエラーに対応するメッセージテキストを
	取得できる。
FORMAT_MESSAGE_ARGUMENT_ARRAY	Arguments パラメータが 1 個の va_list 構造体ではなく、複数の引数を表す値からな
	る 1 つの配列へのポインタであることを指定する。

dwFlags パラメータの下位バイトで、書式化が終わった出力対象のメッセージの 1 行の長さの最大値を指定できる。

この最大値の幅の設定と取得を行うには、FORMAT_MESSAGE_MAX_WIDTH_MASK 値とビット単位の Bool 演算を利用する。
lpSource
メッセージ定義の位置を指定する。このパラメータの意味は、dwFlags パラメータで指定された値によって異なる。

dwFlags の値	lpSource パラメータの意味
FORMAT_MESSAGE_FROM_HMODULE	このパラメータは、検索対象のメッセージテーブルを保持しているモジュールのハンドル。
FORMAT_MESSAGE_FROM_STRING	このパラメータは、書式化されていないメッセージテキストを保持している 1 つの文字列への
	ポインタ。この関数は、この文字列内で挿入シーケンスを検索し、それに従って書式化を
	行なう。

dwFlags パラメータで、前記の 2 つのフラグのどちらも指定されていなかった場合、lpSource パラメータは無視される。
dwMessageId
希望のメッセージのメッセージ識別子を指定する。d

wFlags パラメータで FORMAT_MESSAGE_FROM_STRING フラグを指定した場合は、dwMessageId パラメータは無視される。
dwLanguageId
希望のメッセージの言語識別子を指定する。

dwFlags パラメータで FORMAT_MESSAGE_FROM_STRING フラグを指定した場合は、dwLanguageId パラメータは無視される。
このパラメータで LANGID を指定すると、FormatMessage は、LANGID に一致するメッセージだけを返す。

LANGID に一致するメッセージが見つからなかった場合、ERROR_RESOURCE_LANG_NOT_FOUND が返る。

    このパラメータで 0 を指定すると、FormatMessage は次の順序で、メッセージ指定に使う LANGID を参照する。
    1.特定の言語に依存しない
    2.スレッドのロケール値に基づく、スレッドの LANGID
    3.ユーザーの既定のロケール値に基づく、ユーザーの既定の LANGID
    4.システムの既定のロケール値に基づく、システムの既定の LANGID
    5.US English（アメリカ英語）
    FormatMessage 関数が、これらの LANGID のいずれも見つけられなかった場合、現在存在している任意の言語のメッセージ文字列を

返す。そのような文字列も見つからなかった場合は、ERROR_RESOURCE_LANG_NOT_FOUND を返す。
lpBuffer
1 個のバッファへのポインタを指定する。関数から制御が返ると、このバッファに、書式化が終わった、NULL で終わるメッセージが格納

される。dwFlags パラメータで FORMAT_MESSAGE_ALLOCATE_BUFFER フラグを指定した場合、この関数は LocalAlloc 関数を使っ

て 1 個のバッファを割り当て、lpBuffer で指定されたアドレスに、そのバッファへのポインタを書き込む。
nSize
dwFlags パラメータで FORMAT_MESSAGE_ALLOCATE_BUFFER フラグを指定しなかった場合は、nSize パラメータは、出力バッファ

に格納できる最大の文字数を TCHAR 単位で指定する。dwFlags パラメータで FORMAT_MESSAGE_ALLOCATE_BUFFER フラグを

指定した場合は、出力バッファに割り当てる最小の文字数を TCHAR 単位で指定する。
Arguments
書式化が終わったメッセージ内で挿入シーケンスとして使われる複数の値からなる配列へのポインタを指定する。

書式文字列の %1 は Arguments 配列の最初の要素、、%2 は次の要素を意味する。以下同様。
配列の各要素の解釈は、メッセージ定義内の挿入シーケンスに関連付けられている書式化情報に依存する。

既定では、各値を、NULL で終わる文字列へのポインタとして扱う。
既定では、Arguments パラメータは va_list* 型であり、可変引数を表す言語固有および実装固有のデータ型を意味する。

va_list* 型へのポインタを用意していない場合は、FORMAT_MESSAGE_ARGUMENT_ARRAY フラグを指定し、複数の値からなる

1 つの配列へのポインタを渡す。これらの値は、書式化対象のメッセージへの入力として扱われ、挿入シーケンスの役割を果たす。

    配列内に、各挿入シーケンスに対応する要素が存在していなければならない。
    Windows 95：1 つの挿入文字列の長さは最大 1,023 文字。

戻り値
    関数が成功すると、バッファに格納された TCHAR 単位の文字数が返る。終端の NULL 文字は、この数に含まれない。
    関数が失敗すると、0 が返る。拡張エラー情報を取得するには、GetLastError 関数を使う。