-
MultiByteToWideChar
鎖定
- 中文名
- MultiByteToWideChar
- 映 射
- 一個字符串到一個寬字符的字符串
- 參 數
- CodePage
- 注 意
- GetLastError
- 返回值
- ERROR_INSUFFICIENT
MultiByteToWideChar簡介
函數原型：
int MultiByteToWideChar
UINT CodePage,
DWORD dwFlags,
LPCSTR lpMultiByteStr,
int cchMultiByte,
LPWSTR lpWideCharStr,
int cchWideChar;
補充：如果ANSI代碼頁允許在不同的計算機上不相同，甚至在單台計算機上不一樣，將會導致數據崩潰。為了代碼頁一致性，應用程序應該使用Unicode編碼，如UTF-8或者UTF-16，而不是使用特殊的代碼頁，除了早期標準或者數據格式化不允許使用Unicode編碼。在特殊情況下，有些函數不允許使用Unicode編碼，應用程序應在協議允許的情況下在數據流中用合適的編碼名稱標識。在HTML、XML、HTTP等文件中都允許標識，但TEXT文本不允許這樣做。
MultiByteToWideChar參數
CodePage：指定執行轉換的字符集，這個參數可以為系統已安裝或有效的任何字符集所給定的值。你也可以指定其為下面的任意一值：
CP_SYMBOL：符號字符集（42）；CP_THREAD_ACP：當前線程ANSI代碼頁；
CP_UTF7：使用UTF-7轉換；CP_UTF8：使用UTF-8轉換。
MB_PRECOMPOSED：通常使用預作字符——就是説，由一個基本字符和一個非空字符組成的字符只有一個單一的字符值。這是缺省的轉換選擇。不能與
MB_COMPOSITE值一起使用。
MB_COMPOSITE：通常使用組合字符——就是説，由一個基本字符和一個非空字符組成的字符分別有不同的字符值。不能與MB_PRECOMPOSED值一起使用。
MB_ERR_INVALID_CHARS：如果函數遇到無效的輸入字符，它將運行失敗，且GetLastErro返回ERROR_NO_UNICODE_TRANSLATION值。
MB_USEGLYPHCHARS：使用象形文字替代控制字符。
組合字符由一個基礎字符和一個非空字符構成，每一個都有不同的字符值。每個預作字符都有單一的字符值給基礎/非空字符的組成。在字符è中，e就是基礎字符，而重音符標記就是非空字符。
函數的缺省動作是轉換成預作的形式。如果預作的形式不存在，函數將嘗試轉換成組合形式。
標記MB_PRECOMPOSED和MB_COMPOSITE是互斥的，而標記MB_USEGLYPHCHARS和MB_ERR_INVALID_CHARS則不管其它標記如何都可以設置。
lpMultiByteStr：指向將被轉換字符串的字符。
cchMultiByte：指定由參數lpMultiByteStr指向的字符串中字節的個數。如果lpMultiByteStr指定的字符串以空字符終止，可以設置為-1（如果字符串不是以空字符中止，設置為-1可能失敗，可能成功），此參數設置為0函數將失敗。
lpWideCharStr：指向接收被轉換字符串的緩衝區。
cchWideChar：指定由參數lpWideCharStr指向的緩衝區的寬字符個數。若此值為零，函數返回緩衝區所必需的寬字符數，在這種情況下，lpWideCharStr中的緩衝區不被使用。
MultiByteToWideChar返回值
如果函數運行成功，並且cchWideChar不為零，返回值是由lpWideCharStr指向的緩衝區中寫入的寬字符數；如果函數運行成功，並且cchWideChar為零，返回值是接收到待轉換字符串的緩衝區所需求的寬字符數大小。如果函數運行失敗，返回值為零。若想獲得更多錯誤信息，請調用GetLastError函數。它可以返回下面所列錯誤代碼：
ERROR_INSUFFICIENT_BUFFER；ERROR_INVALID_FLAGS；
ERROR_INVALID_PARAMETER；ERROR_NO_UNICODE_TRANSLATION。
MultiByteToWideChar注意
指針lpMultiByteStr和lpWideCharStr必須不一樣。如果一樣，函數將失敗，GetLastError將返回ERROR_INVALID_PARAMETER的值。
如果MB_ERR_INVALID_CHARS被設置並且在資源字符串中遇到無效的字符時，函數將失敗。如果MB_ERR_INVALID_CHARS不被設置，或是DBCS串中發現了頭字節而沒有有效的尾字節，無效字符將轉換為缺省字符，但不是資源字符串中的缺省字符。當無效字符被發現，且MB_ERR_INVALID_CHARS值被設置，函數返回零，GetLastErro顯示ERROR_NO_UNICODE_TRANSLATION的出錯信息。
如果cchMultiByte為-1，需要注意返回值為包括零字符在內的字符串的總長度比求字符長度函數得到的返回值大1。
Windows CE：不支持參數CodePage中的CP_UTF7和CP_UTF8的值，以及參數dwFlags中的WC_NO_BEST_FIT_CHARS值。
