共用方式為


LCMapStringA 函式 (winnls.h)

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

注意 基於互通性考慮,應用程式應該偏好 使用 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

旗標,指定要在字串對應期間使用的轉換類型,或要產生之排序索引鍵的類型。 如需詳細定義,請參閱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 參數,並傳回對應字串或排序索引鍵所需的緩衝區大小。

傳回值

如果函式在用於字串對應時成功,它會傳回翻譯字串中的字元數, (請參閱 cchSrccchDest 以取得詳細資料) 。

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

如果函式未成功,此函式會傳回 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

另請參閱

CompareString

FindNLSString

GetNLSVersion

處理應用程式中的排序

LCMapStringEx

國家語言支援

國家語言支援函式