WideCharToMultiByte

WideCharToMultiByte

와이드 문자열(Unicode 문자열)을 새로운 문자열(멀티 바이트 문자열 등)로 변환합니다.

int WideCharToMultiByte(
    UINT   uCodePage,       // code page
    DWORD  dwFlags,         // 플래그
    PCWSTR pWideCharStr,    // 변환원의 문자열 주소
    int    cchWideChar,     // 문자열의 길이
    PSTR   pMultiByteStr,   // 버퍼 주소
    int    cchMultiByte,    // 문자열의 길이
    PCSTR  pDefaultChar,    // 디폴트 캐릭터
    PBOOL  pUsedDefaultChar // 플래그를 격납하는 주소
);

KERNEL32.DLL

인수

uCodePage

변환시에 사용되는 code page를 지정합니다.이 파라미터는, 인스톨 되고 있을까 시스템으로 사용 가능하다 모든 code page를 지정할 수 있습니다.또, 이하의 값의1개를 지정할 수도 있습니다.

치	의미
0 (CP_ACP)	ANSI code page
1 (CP_OEMCP)	OEM code page
2 (CP_MACCP)	Macintosh code page
3 (CP_THREAD_ACP)	Windows 2000/XP： 호출 스렛드의 ANSI code page
42 (CP_SYMBOL)	Windows 2000/XP： 심볼 code page
65000 (CP_UTF7)	Windows 98/Me/NT 4.0 이후： UTF-7 (을)를 사용해 변환
65001 (CP_UTF8)	Windows 98/Me/NT 4.0 이후： UTF-8 (을)를 사용해 변환 이것을 지정했을 경우, dwFlags 파라미터는 0 (이)가 아니면 안됩니다.

dwFlags

비트 플래그를 지정합니다. 0 또는 이하의 값의 편성을 지정합니다.

치	의미
0x00000010 (WC_DISCARDNS)	변환시에 논스페이싱캐라크타를 읽고 버립니다.
0x00000020 (WC_SEPCHARS)	변환시에 separate characters (으)로 변환한다.(디폴트)
0x00000040 (WC_DEFAULTCHAR)	변환시에 예외를 디폴트 캐릭터에 바꿉니다.
0x00000200 (WC_COMPOSITECHECK)	composite 캐릭터를 precomposed 캐릭터로 변환합니다.
0x00000400 (WC_NO_BEST_FIT_CHARS)	Windows 2000/XP： 직접 멀티 바이트 문자로 변환할 수 없는 문자를 디폴트 캐릭터에 바꿉니다.

COMPOSITECHECK 플래그가 지정되면, 함수는 composite 캐릭터를 precomposed 캐릭터로 변환합니다. composite 캐릭터는 베이스 캐릭터와 논스페이싱캐라크타로부터 구성되어 각각의 문자가 다른 캐릭터치를 가집니다. precomposed 캐릭터는, 베이스 캐릭터와 논스페이싱캐라크타가 짜 합쳐졌다1개의 캐릭터치를 가집니다.예를 들면, 문자 「 e 」에서는, 「 e 」(이)가 베이스 캐릭터가 되어, 엑센트 기호 「 ` 」(이)가 논스페이싱캐라크타가 됩니다.

COMPOSITECHECK 플래그를 지정할 때에, 어플리케이션은, 변환 방법을 커스터마이즈 하기 위해서 WC_DISCARDNS, WC_SEPCHARS, WC_DEFAULTCHAR 플래그를 사용할 수 있습니다.이러한 플래그는, 와이드 문자열중의 베이스 캐릭터와 논스페이싱캐라크타의 조합해에 대응한다 precomposed 매핑이 존재하지 않는 경우에 어떻게 처리하는지를 결정합니다.이3개의 플래그는 COMPOSITECHECK 플래그가 함께 지정되어 있는 경우에게만 유효합니다.

pWideCharStr

변환원의 와이드 문자열의 주소를 지정합니다.

cchWideChar

pWideCharStr 파라미터로 나타내지는 문자열의 문자수를 지정합니다. -1 (을)를 지정하면, 눌 종단 문자까지로 간주해져 문자수가 자동적으로 계산됩니다.

pMultiByteStr

변환된 문자열을 받는 버퍼의 주소를 지정합니다.

cchMultiByte

pMultiByteStr 파라미터로 지정되는 버퍼의 사이즈를 아르바이트 단위로 지정합니다.

0 (을)를 지정하면, 이 함수는 필요한 버퍼 사이즈를 돌려줍니다.

pDefaultChar

와이드 문자를 지정된 code page로 나타낼 수 없었던 경우에 사용되는 디폴트 캐릭터의 주소를 지정합니다.이 파라미터에 0 (NULL) (을)를 지정하면, 시스템 디폴트치가 사용됩니다.

uCodePage 파라미터에 CP_UTF7 또는 CP_UTF8 (을)를 지정했을 경우는, 이 파라미터에 0 (NULL) (을)를 지정하지 않으면 안됩니다.

pUsedDefaultChar

디폴트 캐릭터가 사용되었는지를 나타내는 플래그를 격납하기 위한 변수의 주소를 지정합니다.변환원의 문자열의1개이상의 와이드 문자를 지정된 code page로 나타낼 수 없었던 경우에는 1 (TRUE) 하지만 격납됩니다.그 이외의 경우에는 0 (FALSE) 하지만 격납됩니다.

이 파라미터에 0 (NULL) (을)를 지정할 수도 있습니다.

uCodePage 파라미터에 CP_UTF7 또는 CP_UTF8 (을)를 지정했을 경우는, 이 파라미터에 0 (NULL) (을)를 지정하지 않으면 안됩니다.

반환값

cchMultiByte 파라미터에 0 이외의 값을 지정하고 함수가 성공했을 경우,pMultiByteStr 파라미터가 나타내 보이는 버퍼에 카피된 문자열의 사이즈(아르바이트 단위)가 돌아갑니다.

cchMultiByte 파라미터에 0 (을)를 지정하고 함수가 성공했을 경우, 문자열을 변환하는데 필요한 버퍼 사이즈가 문자수단위로 돌아갑니다.

함수가 실패하면 0 하지만 돌아갑니다.확장 에러 정보를 취득하려면 , GetLastError 함수를 사용합니다. GetLastError 함수는 이하의 값을 돌려줍니다.

• 87 (ERROR_INVALID_PARAMETER)
• 112 (ERROR_INSUFFICIENT_BUFFER)
• 1004 (ERROR_INVALID_FLAGS)

해설

pMultiByteStr 파라미터와 pWideCharStr 파라미터에는 같은 주소를 지정 해서는 안됩니다.같은 주소를 지정했을 경우에는 함수는 실패해 GetLastError 함수가 87 (ERROR_INVALID_PARAMETER) (을)를 돌려줍니다.

대응 정보

Windows 95 이후 / Windows NT 3.1 이후