int WideCharToMultiByte(CodePage, dwFlags, lpWideCharStr, cchWideChar, lpMultiByteStr, cchMultiByte, lpDefaultChar, lpUsedDefaultChar) | |||
UINT CodePage; | |||
DWORD dwFlags; | |||
LPWSTR lpWideCharStr; | |||
int cchWideChar; | |||
LPSTR lpMultiByteStr; | |||
int cchMultiByte; | |||
LPSTR lpDefaultChar; | |||
LPBOOL lpUsedDefaultChar; |
The WideCharToMultiByte function is used to map a wide character string to its multibyte character string counterpart.
CodePage
Code page used to perform the conversion. If CodePage is CP_ACP, the ANSI code page is used. If CodePage is CP_OEMCP, the OEM code page is used.
dwFlags
There are two categories of flags here. The first category is for performance. By not setting these flags, the routine will not do any extraneous checks. The performance flags are:
Value | Meaning |
WC_DEFAULTCHECK | ||
check for default char and set lpUsedDefaultChar | ||
WC_COMPOSITECHECK | ||
convert composite chars to precomposed |
The second category of flags are used only if the WC_COMPOSITECHECK flags is set. These flags handle the case when there is no precomposed mapping for a base/nonspace character combination in the wide character string. The default is to generate separate characters (WC_SEPCHARS). The flags include:
Value | Meaning |
WC_DISCARDNS | ||
discard non-spacing characters | ||
WC_SEPCHARS | ||
generate separate characters (default) | ||
WC_DEFAULTCHAR | ||
replace exceptions with default character |
lpWideCharStr
Pointer to the wide character string to be converted. If cchWideChar is -1, the string is assumed to be null-terminated.
cchWideChar
Character count of string pointed to by lpWideCharStr.
lpMultiByteStr
Pointer to memory buffer which receives the translated multibyte character string.
cchMultiByte
The character count of the memory buffer pointed to by lpMultiByteStr . If cchMultiByte is 0, then the function returns the number of characters required to hold the translated string. lpMultiByteStr is not referenced in this case.
lpDefaultChar
Pointer to the multibyte character used if a wide character is not representable in CodePage . If lpDefaultChar is NULL, a system default value will be used. If the WC_DEFAULTCHECK flag is set, this parameter will be ignored.
lpUsedDefaultChar
Pointer to the boolean location to set indicating that a default character was used. It is set to TRUE if one or more wide characters in the source string are not representable in CodePage ; FALSE otherwise. If the WC_DEFAULTCHECK flag is set, this parameter will be ignored.
Success: number of multi-byte characters returned
Failure: 0
This function sets GetLastError with the following errors: ERROR_INSUFFICIENT_BUFFER, ERROR_INVALID_PARAMETER.
The lpMultiByteStr and lpWideCharStr pointers may NOT be the same; in this case the error ERROR_INVALID_PARAMETER results.