LCMapStringA 函式 (winnls.h)

發行項
08/27/2023

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

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

語法

int LCMapStringA(
  [in]            LCID   Locale,
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

參數

[in] Locale

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

也支援下列自訂地區設定識別碼。

[in] dwMapFlags

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

[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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll