IdnToUnicode function (winnls.h)

Article
10/13/2021

Converts the Punycode form of an internationalized domain name (IDN) or another internationalized label to the normal Unicode UTF-16 encoding syntax.

Caution This function implements the RFC 3490: Internationalizing Domain Names in Applications (IDNA) standard algorithms for the Punycode encoding of Unicode. The standard introduces some security issues. One issue is that glyphs representing certain characters from different scripts might appear similar or even identical. For example, in many fonts, Cyrillic lowercase A ("а") is indistinguishable from Latin lowercase A ("a"). There is no way to tell visually that "example.com" and "exаmple.com" are two different domain names, one with a Latin lowercase A in the name, the other with a Cyrillic lowercase A. For more information about IDN-related security concerns, see Handling Internationalized Domain Names (IDNs).

Syntax

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

Parameters

[in] dwFlags

Flags specifying conversion options. For detailed definitions, see the dwFlags parameter of IdnToAscii.

[in] lpASCIICharStr

Pointer to a string representing the Punycode encoding of an IDN or another internationalized label. This string must consist only of ASCII characters, and can include Punycode-encoded Unicode. The function decodes Punycode values to their UTF-16 values.

[in] cchASCIIChar

Count of characters in the input string indicated by lpASCIICharStr.

[out, optional] lpUnicodeCharStr

Pointer to a buffer that receives a normal Unicode UTF-16 encoding equivalent to the Punycode value of the input string. Alternatively, the function can retrieve NULL for this parameter, if cchUnicodeChar set to 0. In this case, the function returns the size required for this buffer.

[in] cchUnicodeChar

Size, in characters, of the buffer indicated by lpUnicodeCharStr. The application can set the size to 0 to retrieve NULL in lpUnicodeCharStr and have the function return the required buffer size.

Return value

Returns the number of characters retrieved in lpUnicodeCharStr if successful. The retrieved string is null-terminated only if the input string is null-terminated.

If the function succeeds and the value of cchUnicodeChar is 0, the function returns the required size, in characters including a terminating null character if it was part of the input buffer.

The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
ERROR_INVALID_NAME. An invalid name was supplied to the function. Note that this error code catches all syntax errors.
ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
ERROR_NO_UNICODE_TRANSLATION. Invalid Unicode was found in a string.

Remarks

See Remarks for IdnToAscii.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	winnls.h (include Windows.h)
Library	Normaliz.lib
DLL	Normaliz.dll
Redistributable	Microsoft Internationalized Domain Name (IDN) Mitigation APIs onWindows XP with SP2 and later, orWindows Server 2003 with SP1