-
WideCharToMultiByte
鎖定
- 中文名
- 寬字符到多字節
- 外文名
- WideCharToMultiByte
- 類 型
- 函數
- 作 用
- 執行轉換的代碼頁
WideCharToMultiByte基本介紹及功能
WideCharToMultiByte
函數原型：
int WideCharToMultiByte( UINT CodePage, //指定執行轉換的代碼頁 DWORD dwFlags, //允許你進行額外的控制，它會影響使用了讀音符號（比如重音）的字符 LPCWSTR lpWideCharStr, //指定要轉換為寬字節字符串的緩衝區 int cchWideChar, //指定由參數lpWideCharStr指向的緩衝區的字符個數 LPSTR lpMultiByteStr, //指向接收被轉換字符串的緩衝區 int cchMultiByte, //指定由參數lpMultiByteStr指向的緩衝區最大值 LPCSTR lpDefaultChar, //遇到一個不能轉換的寬字符，函數便會使用pDefaultChar參數指向的字符 LPBOOL pfUsedDefaultChar //至少有一個字符不能轉換為其多字節形式，函數就會把這個變量設為TRUE );
參數：
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 e is 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) |
WideCharToMultiByte相關變量
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。
