IdnToAscii 函数 (winnls.h)

项目
03/04/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) Charter。
IDN_RAW_PUNYCODE	从 Windows 8 开始：禁用 Punycode 的验证和映射。

[in] lpUnicodeCharStr

指向表示 IDN 或其他国际化标签的 Unicode 字符串的指针。

[in] cchUnicodeChar

lpUnicodeCharStr 指示的输入 Unicode 字符串中的字符计数。

[out, optional] lpASCIICharStr

指向接收仅包含 ASCII 字符集中字符的 Unicode 字符串的缓冲区的指针。从此函数返回时，缓冲区包含与 Punycode 下的 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 终止。若要以 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 的一部分，这些 API 不再可供下载。

要求

要求	值
最低受支持的客户端	Windows Vista [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	winnls.h (包括 Windows.h)
Library	Normaliz.lib
DLL	Normaliz.dll
可再发行组件	Microsoft 国际化域名 (IDN) 缓解 API，Windows XP SP2 及更高版本，Windows Server 2003 SP1

另请参阅

通过

IdnToAscii 函数 (winnls.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源