基本介绍及功能

相关变量

基本介绍及功能

WideCharToMultiByte

函数功能：该函数映射一个unicode字符串到一个多字节字符串。

函数原型：

int WideCharToMultiByte(

UINT CodePage, //指定执行转换的代码页

DWORD dwFlags,

LPCWSTR lpWideCharStr, //指定的宽字节字符串的缓冲区

int cchWideChar, //指定由参数lpWideCharStr指向的缓冲区的字符个数

LPSTR lpMultiByteStr, //指向接收被转换字符串的缓冲区

int cchMultiByte, //指定由参数lpMultiByteStr指向的缓冲区最大值

LPCSTR lpDefaultChar,

LPBOOL pfUsedDefaultChar

);

参数：

CodePage：指定执行转换的代码页，这个参数可以为系统已安装或有效的任何代码页所给定的值。你也可以指定其为下面的任意一值：

CP_ACP：ANSI代码页；CP_MACCP：Macintosh代码页；CP_OEMCP：OEM代码页；

CP_SYMBOL：符号代码页（42）；CP_THREAD_ACP：当前线索ANSI代码页；

CP_UTF7：使用UTF-7转换；CP_UTF8：使用UTF-8转换。

dwFlags[in] Specifies the handling of unmapped characters. The function performs more quickly when none of these flags is set. The following flag constants are defined.

Value　Meaning

WC_NO_BEST_FIT_CHARS　Windows 98/Me and Windows 2000/XP: Any Unicode characters that do not translate directly to multibyte equivalents are translated to the default character (see lpDefaultCharparameter). In other words, if translating from Unicode to multibyte and back to Unicode again does not yield the exact same Unicode character, the default character is used. This flag can be used by itself or in combination with the other dwFlagoptions.

WC_COMPOSITECHECK　Convert composite characters to precomposed characters.

WC_DISCARDNS　Discard nonspacing characters during conversion.

WC_SEPCHARS　Generate separate characters during conversion. This is the default conversion behavior.

WC_DEFAULTCHAR　Replace exceptions with the default character during conversion.　When WC_COMPOSITECHECK is specified, the function converts composite characters to precomposed characters. A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/nonspacing character combination. In the character , the eis the base character, and the accent grave mark is the nonspacing character.

When an application specifies WC_COMPOSITECHECK, it can use the last three flags in this list (WC_DISCARDNS, WC_SEPCHARS, and WC_DEFAULTCHAR) to customize the conversion to precomposed characters. These flags determine the function's behavior when there is no precomposed mapping for a base/nonspace character combination in a wide-character string. These last three flags can only be used if the WC_COMPOSITECHECK flag is set.

The function's default behavior is to generate separate characters (WC_SEPCHARS) for unmapped composite characters.

For the code pages in the following table, dwFlagsmust be zero, otherwise the function fails with ERROR_INVALID_FLAGS.

50220 50221
50222
50225　50227 50229
52936
54936　57002 through 57011 65000 (UTF7)
65001 (UTF8)
42 (Symbol)

相关变量

lpWideCharStr：指向将被转换的unicode字符串。

cchWideChar：指定由参数lpWideCharStr指向的缓冲区的字符个数。如果这个值为-1，字符串将被设定为以NULL为结束符的字符串，并且自动计算长度。

lpMultiByteStr：指向接收被转换字符串的缓冲区。

cchMultiByte：指定由参数lpMultiByteStr指向的缓冲区最大值（用字节来计量）。若此值为零，函数返回lpMultiByteStr指向的目标缓冲区所必需的字节数，在这种情况下，lpMultiByteStr参数通常为NULL。

lpDefaultChar和pfUsedDefaultChar：只有当WideCharToMultiByte函数遇到一个宽字节字符，而该字符在uCodePage参数标识的代码页中并没有它的表示法时，WideCharToMultiByte函数才使用这两个参数。如果宽字节字符不能被转换，该函数便使用lpDefaultChar参数指向的字符。如果该参数是NULL（这是大多数情况下的参数值），那么该函数使用系统的默认字符。该默认字符通常是个问号。这对于文件名来说是危险的，因为问号是个通配符。pfUsedDefaultChar参数指向一个布尔变量，如果Unicode字符串中至少有一个字符不能转换成等价多字节字符，那么函数就将该变量置为TRUE。如果所有字符均被成功地转换，那么该函数就将该变量置为FALSE。当函数返回以便检查宽字节字符串是否被成功地转换后，可以测试该变量。

返回值：如果函数运行成功，并且cchMultiByte不为零，返回值是由 lpMultiByteStr指向的缓冲区中写入的字节数；如果函数运行成功，并且cchMultiByte为零，返回值是接收到待转换字符串的缓冲区所必需的字节数。如果函数运行失败，返回值为零。若想获得更多错误信息，请调用GetLastError函数。它可以返回下面所列错误代码：

ERROR_INSUFFICIENT_BJFFER；ERROR_INVALID_FLAGS；

ERROR_INVALID_PARAMETER；ERROR_NO_UNICODE_TRANSLATION。

注意：指针lpMultiByteStr和lpWideCharStr必须不一样。如果一样，函数将失败，GetLastError将返回ERROR_INVALID_PARAMETER的值。

Windows CE：不支持参数CodePage中的CP_UTF7和CP_UTF8的值，以及参数dwFlags中的WC_NO_BEST_FIT_CHARS值。

速查：Windows NT 3.1、Windows 95以上、Windows CE 1.0以上，头文件：winnls.h；库文件：kernel32.lib。