FormatMessage(A)

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 함수를 사용합니다.

해설

메세지 정의에는, 서식화를 위한 서식 지정자를 포함할 수 있습니다.서식 지정자의 예를 다음에 나타냅니다.

서식 지정자	의미
%수치!서식 지정자!	삽입구의 매입 장소를 지시합니다. 「%수치」에는,%의 후에1이상99이하의 숫자를 지정합니다.「%1」(이)가 Arguments 파라미터로 지정한 배열의 최초의 요소에, 「%2」(이)가 다음의 요소에 대응합니다.이하 와 같습니다. 「!서식 지정자!」에는, printf 함수로 사용하는 서식 지정자( 「!s!」(이)나 「!d!」 등)을 지정합니다.다만, 「!e!」 「!E!」 「!f!」 「!g!」(은)는 사용할 수 없습니다.「!서식 지정자!」(을)를 지정하지 않았던 경우는, 「!s!」(이)가 지정된 것으로 간주해집니다.
%%	퍼센트 기호(%)
%n	개행

대응 정보

Windows 95 이후 / Windows NT 3.1 이후