LCMapStringW 函式（winnls.h）

發行項
11/20/2024

針對標識元所指定的地區設定，使用指定的轉換，將一個輸入字元字串對應到另一個地區設定，或產生輸入字元串的排序索引鍵。

注意基於互操作性考慮，應用程式應該偏好使用 LCMapStringEx 函式來 LCMapString，因為Microsoft正移轉至使用地區設定名稱，而不是新地區設定的地區設定標識符。這項建議特別適用於自定義地區設定，包括Microsoft所建立的地區設定。只有在 Windows Vista 和更新版本上執行的任何應用程式都應該使用 LCMapStringEx。

語法

int LCMapStringW(
  [in]            LCID    Locale,
  [in]            DWORD   dwMapFlags,
  [in]            LPCWSTR lpSrcStr,
  [in]            int     cchSrc,
  [out, optional] LPWSTR  lpDestStr,
  [in]            int     cchDest
);

參數

[in] Locale

指定地區設定的地區設定標識碼。您可以使用 MAKELCID 巨集來建立地區設定識別碼，或使用下列其中一個預先定義的值。

也支援下列自定義地區設定標識碼。

[in] dwMapFlags

旗標，指定要在字串對應期間使用的轉換類型或要產生的排序索引鍵類型。如需詳細定義，請參閱 LCMapStringExdwMapFlags 參數。

[in] lpSrcStr

函式對應或用於排序索引鍵產生的來源字串指標。此字串的大小不能是 0。

[in] cchSrc

大小，以字元為單位，lpSrcStr 所指示的來源字串。來源字串的大小可以包含終止的 Null 字元，但不需要。如果包含終止的 Null 字元，函式的對應行為不會受到很大影響，因為終止的 Null 字元會被視為無法排序，而且一律會對應至本身。

應用程式可以將參數設定為任何負值，以指定來源字串為 Null 終止。在此情況下，如果 LCMapString 用於其字串對應模式，則函式會計算字串長度本身，並以 null 結束 lpDestStr所指示的對應字元串。

應用程式無法將此參數設定為 0。

[out, optional] lpDestStr

這個函式擷取對應字串或排序索引鍵之緩衝區的指標。

如果應用程式使用函式來產生排序索引鍵（LCMAP_SORTKEY）：

排序索引鍵會儲存在緩衝區中，並視為不透明的位元組陣列。預存值可以包含任何位置的內嵌 0 個字節。
目的地字串可以包含奇數位節數。 LCMAP_BYTEREV旗標只會反轉偶數個字節。排序索引鍵中的最後一個字節（奇置位置）不會反轉。

如果呼叫端明確要求字串的子集，除非呼叫者在 cchDest中指定，否則目的地字串不會包含終止的 null 字元。

如果此函式失敗，目的地緩衝區可能會包含部分結果或完全沒有結果。在此情況下，所有結果都應該視為無效。

注意

設定LCMAP_UPPERCASE或LCMAP_LOWERCASE時，目的地字串可以使用與來源字元串相同的緩衝區。不過，強烈建議您不要這樣做，因為某些條件可能會導致傳回的大小寫字串長度不同。

[in] cchDest

lpDestStr 所指示之目的地字串的大小，以字元為單位，。如果應用程式使用函式進行字串對應，則會提供此參數的字元計數。如果終止 Null 字元的空間包含在 cchSrc中，cchDest 也必須包含終止 Null 字元的空間。

如果應用程式使用函式來產生排序索引鍵，則會提供大小的位元組計數。此位元組計數必須包含排序索引鍵0x00終止符的空間。

應用程式可以將 cchDest 設定為 0。在此情況下，函式不會使用 lpDestStr 參數，並傳回對應字串或排序索引鍵所需的緩衝區大小。

傳回值

如果函式在用於字串對應時成功，則會傳回翻譯字串中的字元數（如需詳細資訊，請參閱 cchSrc ，並 cchDest）。

如果函式用於字串對應時成功，則會傳回排序索引鍵中的位元元組數目。

如果函式未成功，則此函式會傳回 0。若要取得擴充的錯誤資訊，應用程式可以呼叫 getLastError，以傳回下列其中一個錯誤碼：

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 NULL不正確。
ERROR_INVALID_FLAGS。為旗標的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。

如果函式未成功，則此函式會傳回 0。若要取得擴充的錯誤資訊，應用程式可以呼叫 getLastError，以傳回下列其中一個錯誤碼：

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 NULL不正確。
ERROR_INVALID_FLAGS。為旗標的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。

言論

請參閱 LCMapStringEx的備註。

ANSI 版本的 LCMapString 會根據與指定地區設定相關聯的預設 Windows （ANSI）代碼頁，從 Unicode 對應字串。當此函式的 ANSI 版本與僅限 Unicode 的地區設定搭配使用時，函式可能會成功，因為操作系統會使用 CP_ACP 值，代表系統預設的 Windows ANSI 代碼頁。不過，系統代碼頁中未定義的字元會以問號（？）的形式出現在字串中。

注意

winnls.h 標頭會將 LCMapString 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winnls.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll