基本介紹
- 中文名：寬字元到多位元組
- 外文名：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) |
相關變數
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。
