WideCharToMultiByte() 的用法(MSDN)

国际特色

WideCharToMultiByte

函数WideCharToMultiByte一个宽字符的字符串映射到一个新的字符串。新的字符串不一定是多字节字符集。

诠释WideCharToMultiByte（

UINT代码页，/ /代码页

DWORD dwFlags中，/ /性能和测绘标志

LPCWSTR lpWideCharStr，/ /宽字符字符串

cchWideChar，/ /字符串中的字符数。

LPSTR lpMultiByteStr，/ /新的字符串缓冲区

cbMultiByte，/ /缓冲区的大小

LPCSTR lpDefaultChar，/ /默认为不可映射字符

LPBOOL lpUsedDefaultChar / /设置时默认使用CHAR

）;

参数

代码页

[in]指定使用的代码页进行转换。此参数可被安装或在系统中可用的任何代码页的值。有关代码页的列表，请参见代码页标识符。您还可以指定下列值之一。值含义

CP_ACP ANSI代码页

CP_MACCP Macintosh代码页

CP_OEMCP OEM代码页

CP_SYMBOL的Windows 2000/XP：符号的代码页（42）

的CP_THREAD_ACP Windows 2000/XP：当前线程的ANSI代码页

CP_UTF7 Windows 98/Me中，Windows NT 4.0和更高版本：翻译使用UTF-7。当此设置，必须为NULL lpDefaultChar和lpUsedDefaultChar

CP_UTF8 Windows 98/Me中，Windows NT 4.0和更高版本：翻译使用UTF-8。当此设置，dwFlags中必须是零和两个lpDefaultChar lpUsedDefaultChar必须为NULL。

的Windows 95：根据微软的Unicode，WideCharToMultiByte还支持CP_UTF7个个CP_UTF8。

dwFlags中

[in]指定的处理未映射字符。函数执行时更快速地设置这些标志没有。下面的标志常量的定义。值含义

WC_NO_BEST_FIT_CHARS的Windows 98/Me和Windows 2000/XP的任何Unicode字符不能直接转换为多字节等值换算的默认字符（见lpDefaultChar参数）。换句话说，如果从Unicode转换为多字节和背部再次为Unicode不会产生相同的Unicode字符，使用默认的字符。

此标志可以用于本身或结合其他dwFlag选择。

WC_COMPOSITECHECK转换复合字符，到的预字符。

WC_DISCARDNS丢弃在转换过程中的非空格字符。

WC_SEPCHARS生成单独的字符转换过程中。这是默认的转换行为。

WC_DEFAULTCHAR在转换过程中的默认字符替换例外。

指定WC_COMPOSITECHECK时，功能复合字符转换到的预字符。复合字符由一个基本字符和一个非空格字符，每一个都有不同的字符值。预字符基地/非空格字符组合有一个单一的字符值。字符，电子是基础字符，重音符号标记的非空格字符。

当应用程序指定WC_COMPOSITECHECK的，它可以使用此列表中的最后三个标志（WC_DISCARDNS，的WC_SEPCHARS，WC_DEFAULTCHAR）以自定义转换的预字符的。这些标志时，判断函数的行为没有任何的预映射基地/非空格字符组合在一个宽字符的字符串。最后这三个标志只能用于，如果

WC_COMPOSITECHECK标志设置。

该函数的默认行为是未映射的复合字符生成单独的的字符（WC_SEPCHARS）的。

对于下表中的代码页的dwFlags中必须为零，否则函数失败与

ERROR_INVALID_FLAGS。50220

50221

50222

50225

50227

50229

52936

54936

57002至57011

65000（UTF7，）

65001（UTF8）

42（符号）

lpWideCharStr

[]指向宽字符字符串转换。

cchWideChar

[in]指定到由lpWideCharStr参数指向的字符串中的宽字符数。如果这个值是-1，则该字符串被假定为是空终止，并自动计算长度。长度将包括空终止符。

需要注意的是如果cchWideChar是零函数失败。

lpMultiByteStr

[OUT]指向接收缓冲区翻译的字符串。

cbMultiByte

[in]指定的大小，以字节为单位，到由lpMultiByteStr参数指向的缓冲区。如果这个值是零，则函数返回所需缓冲区的字节数。（在这种情况下，不使用的lpMultiByteStr缓冲区）。

lpDefaultChar

[]指向一个宽字符不能在指定的代码页中表示使用的字符。如果此参数为NULL，系统则使用默认值。要获取系统默认的字符，如果一个宽字符不能在指定的代码页中表示，使用的GetCPInfo或GetCPInfoEx功能。功能是更快，当两个lpDefaultChar lpUsedDefaultChar为NULL。

对于的dwFlags中提到的代码页，lpDefaultChar必须为NULL，否则函数将失败，ERROR_INVALID_PARAMETER。

lpUsedDefaultChar

[]指向一个标志，指示是否使用一个默认的字符。标志设置为TRUE，如果一个或多个源字符串中的宽字符不能表示在指定的代码页。否则，该标志设置为false。此参数可以为NULL。功能是更快，当两个lpDefaultChar lpUsedDefaultChar为NULL。

对于的dwFlags中提到的代码页，lpUsedDefaultChar必须为NULL，否则函数将失败，ERROR_INVALID_PARAMETER。

返回值

如果函数调用成功，非零和cbMultiByte，返回值是多少字节写入缓冲区的由lpMultiByteStr指出。这个数字包括空终止字节。

如果函数调用成功，并cbMultiByte为零，返回值是所需的大小，以字节为单位，一个缓冲区，可以接收翻译的字符串。

如果函数失败，返回值是零。为了得到扩展的错误信息，调用GetLastError。GetLastError函数可能会返回以下错误代码之一：

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

备注

WideCharToMultiByte函数的安全提示使用不当，可能会危及您的应用程序的安

全性。调用WideCharToMultiByte函数，可以很容易地导致缓冲区溢出，因为在缓冲区的大小的数目等于字符串中的WCHARs，而离开缓冲区的大小的字节数相等。为了避免缓冲区溢出，一定要指定一个适当的数据类型的缓冲区接收缓冲区大小。欲了解更多信息，请参阅安全注意事项：国际特点。

对于需要验证的字符串，如文件，资源和用户名，请务必使用WideCharToMultiByte WC_NO_BEST_FIT_CHARS标志。此标志禁止从字符映射字符出现相似，但有很大的不同语义功能。在某些情况下，语义的变化可以是极端的，例如，标志为'∞（无穷大）映射到8（八）在某些代码页。

不可WC_NO_BEST_FIT_CHARS在Windows 95和NT4。如果您的代码必须运行在这些平台上，你可以达到同样的效果往返字符串使用MultiByteToWideChar。不往返的任何代码点是一个最合适的字符。

的lpMultiByteStr和lpWideCharStr指针必须是不一样的。如果它们是相同的，该函数将失败，GetLastError返回ERROR_INVALID_PARAMETER。

如果代码页是CP_SYMBOL的，和cbMultiByte小于cchWideChar的，没有字符被书面lpMultiByte的，。否则，如果cbMultiByte是小于cchWideChar的，cbMultiByte字符复制到由lpMultiByte指向的缓冲区。

应用程序可以使用的lpDefaultChar参数，用于转换来改变默认的字符。

如前所述，WideCharToMultiByte函数最有效地运行时lpDefaultChar lpUsedDefaultChar是NULL。下表显示了四个的组合lpDefaultChar lpUsedDefaultChar WideCharToMultiByte的行为。

lpDefaultChar lpUsedDefaultChar结果

NULL NULL没有默认的检查。这是最有效的方式使用此功能。

非NULL NULL使用指定的默认字符，但不设置lpUsedDefaultChar。

非NULL NULL使用系统默认的字符和如有必要设置lpUsedDefaultChar。

非空非空使用指定的默认字符和如有必要设置lpUsedDefaultChar。

Windows 95/98/Me的：WideCharToMultiByte是由微软的Unicode支持。要使用此功能，您必须添加特定的文件到您的应用程序，在Windows 95/98/Me的系统在微软的Unicode概述。

示例代码

举一个例子，看到寻找用户的姓名。

要求

在Windows NT 3.1和更高版本的Windows NT/2000/XP：包括。

Windows 95/98/Me的：包括在Windows 95和更高版本。

部首：申报Winnls.h;包含windows.h。

库：使用KERNEL32.LIB。

参见

Unicode和字符集概述，Unicode和字符集函数，MultiByteToWideChar -------------------------------------------------- ------------------------------

?2005微软公司。保留所有权利。

要求

在Windows NT 3.1和更高版本的Windows NT/2000/XP：包括。Windows 95/98/Me的：包括在Windows 95和更高版本。

部首：申报Winnls.h;包含windows.h。

库：使用KERNEL32.LIB。

参见

Unicode和字符集概述，Unicode和字符集函数，MultiByteToWideChar -------------------------------------------------- ------------------------------

?2005微软公司。保留所有权利。

撤消修改