IdnToAscii 函式 (winnls.h)

發行項
03/13/2024

將國際化功能變數名稱 (IDN) 或其他國際化標籤轉換成 Unicode (寬字元) 表示 ASCII 字串串，此字串代表 Punycode 傳輸編碼語法中的名稱。

謹慎此函式會實作 RFC 3490：在應用程式 (IDNA 中將域名國際化) 標準演算法，以便將 IDN 轉換為 Punycode。標準引進一些安全性問題。其中一個問題是，代表不同腳本中特定字元的字元可能類似或甚至相同。例如，在許多字型中，斯拉夫文小寫 A (“а”) 從拉丁小寫 A (“a”) 不區分。無法以可視化方式告訴「example.com」和「exа mple.com」是兩個不同的功能變數名稱，一個名稱中有拉丁小寫 A，另一個則以斯拉夫文小寫 A。如需 IDN 相關安全性考慮的詳細資訊，請參閱處理國際化功能變數名稱 (IDN) 。

語法

int IdnToAscii(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpUnicodeCharStr,
  [in]            int     cchUnicodeChar,
  [out, optional] LPWSTR  lpASCIICharStr,
  [in]            int     cchASCIIChar
);

參數

[in] dwFlags

指定轉換選項的旗標。下表列出可能的值。

值	意義
IDN_ALLOW_UNASSIGNED	注意如果應用程式只是使用查詢字串進行一般查閱，則應用程式可以設定此值，如同比較作業一樣。不過，應用程式不應該為預存字串設定此值，這是準備用於記憶體的字串。允許在輸入字串中包含未指派的程式代碼點。默認值為不允許未指派的代碼點，並失敗並出現擴充的錯誤碼ERROR_INVALID_NAME。此旗標可讓函式處理目前在IDN中不是合法的字元，但在較新版本的 IDNA 標準中可能合法。如果您的應用程式將未指派的代碼點編碼為 Punycode，產生的功能變數名稱應該不合法。如果較新版本的 IDNA 讓這些名稱合法，或應用程式篩選出不合法的字元，嘗試建立合法功能變數名稱，則安全性可能會遭到入侵。如需詳細資訊，請參閱 ) 處理國際化功能變數名稱 (IDN 。
IDN_USE_STD3_ASCII_RULES	篩選出 STD3 名稱中不允許的 ASCII 字元。輸入 Unicode 字串中唯一允許的 ASCII 字元是字母、數位和連字元減號。字串不能以連字元減號開頭或結尾。如果輸入 Unicode 字串包含無法出現在功能變數名稱中的 ASCII 字元，例如 “[”、“]” 或 “/”，函式就會失敗。注意有些局域網路可以在計算機名稱中允許其中一些字元。如果輸入 Unicode 字串包含控制字元， (U+0001 到 U+0020) 或 “delete” 字元 (U+007F) ，則函式會失敗。不論是哪一種情況，此旗標都不會影響 Unicode 字串中允許的非 ASCII 字元。
IDN_EMAIL_ADDRESS	從 Windows 8 開始：針對電子郵件位址的本機部分啟用 EAI 演算法後援 (，例如<local>@microsoft.com) 。當電子郵件地址有無效的位址或語法時，此函式的預設值會失敗。應用程式可以設定此旗標來啟用 Email 位址國際化 (EAI) ，以盡可能傳回可探索的後援位址。如需詳細資訊，請參閱 IETF Email 地址國際化 (eai) 。
IDN_RAW_PUNYCODE	從 Windows 8 開始：停用 Punycode 的驗證和對應。

[in] lpUnicodeCharStr

代表IDN或其他國際化捲標的 Unicode 字串指標。

[in] cchUnicodeChar

輸入 Unicode 字串中以 lpUnicodeCharStr 表示的字元計數。

[out, optional] lpASCIICharStr

緩衝區的指標，這個緩衝區只包含 ASCII 字元集中的字元所組成的 Unicode 字串。從此函式傳回時，緩衝區會包含與 lpUnicodeCharStr 底下 lpUnicodeCharStr 中提供的字串相等的 ASCII 字串。或者，如果 cchASCIIChar 設定為 0，則函式可以擷取此參數的 NULL。在此情況下，函式會傳回此緩衝區所需的大小。

[in] cchASCIIChar

lpASCIICharStr 所指示的緩衝區大小。應用程式可以將參數設定為0，以擷取 lpASCIICharStr 中的 NULL。

傳回值

如果成功，則會傳回 在 lpASCIICharStr 中擷取的字元數。只有在輸入 Unicode 字串為 null 終止時，擷取的字串才會以 Null 終止。

如果函式成功，且 cchASCIIChar 的值為 0，則函式會傳回所需的大小，如果它是輸入緩衝區的一部分，則包含終止 Null 字元。

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

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 NULL 不正確。
ERROR_INVALID_FLAGS。為旗標的值無效。
ERROR_INVALID_NAME。函式提供無效的名稱。請注意，此錯誤碼會攔截所有語法錯誤。
ERROR_INVALID_PARAMETER。任何參數值都無效。
ERROR_NO_UNICODE_TRANSLATION。在字串中找到無效的 Unicode。

備註

如果明確指定輸入字串長度而不結束 Null 字元，則函式不會以 Null 結束輸出字串。若要為這個函式終止輸出字串，應用程式應該為 cchUnicodeChar 參數提供 -1，或明確計算輸入字串的終止 Null 字元。

請注意，如果輸入字串包含控制字元 (U+0001 到 U+0020) 或 “delete” 字元 (U+007F) ，則函式一律會失敗。由於U+0000字元只能顯示為終止Null字元，因此如果U+0000出現在輸入字串中的其他位置，則函式一律會失敗。

Windows XP、Windows Server 2003：

不再支援。

必要的頭檔與 DLL 是 Microsoft 國際化功能變數名稱 (IDN) 風險降低 API 的一部分，無法再下載。

規格需求

需求	值
最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Normaliz.lib
Dll	Normaliz.dll
可轉散發套件	Microsoft 國際化功能變數名稱 (IDN) Windows XP 上 SP2 和更新版本的風險降低 API，Windows Server 2003 SP1

另請參閱

共用方式為

IdnToAscii 函式 (winnls.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

其他資源