IdnToAscii

Converts an internationalized domain name (IDN) or another internationalized label to a Unicode (wide character) representation of the ASCII string that represents the name in the Punycode transfer encoding syntax.

Caution

This function implements the RFC 3490: Internationalizing Domain Names in Applications (IDNA) standard algorithm for converting an IDN to Punycode. 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 IdnToAscii(
         DWORD dwFlags,
         _In_reads_(cchUnicodeChar)LPCWSTR lpUnicodeCharStr,
         int cchUnicodeChar,
         _Out_writes_opt_(cchASCIIChar)LPWSTR lpASCIICharStr,
         int cchASCIIChar
)  

Parameters

dwFlags
Type: DWORD 

Flags specifying conversion options. The following table lists the possible values.

lpUnicodeCharStr
Type: In_reads(cchUnicodeChar)LPCWSTR 

Pointer to a Unicode string representing an IDN or another internationalized label.

cchUnicodeChar
Type: int 

Count of characters in the input Unicode string indicated by lpUnicodeCharStr.

lpASCIICharStr
Type: Out_writes_opt(cchASCIIChar)LPWSTR 

Pointer to a buffer that receives a Unicode string consisting only of characters in the ASCII character set. On return from this function, the buffer contains the ASCII string equivalent of the string provided in lpUnicodeCharStr under Punycode. Alternatively, the function can retrieve NULL for this parameter, if cchASCIIChar is set to 0. In this case, the function returns the size required for this buffer.

cchASCIIChar
Type: int 

Size of the buffer indicated by lpASCIICharStr. The application can set the parameter to 0 to retrieve NULL in lpASCIICharStr.

Return value

Type: int 

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

If the function succeeds and the value of cchASCIIChar 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

The function does not null-terminate an output string if the input string length is explicitly specified without a terminating null character. To null-terminate an output string for this function, the application should supply -1 for the cchUnicodeChar parameter or explicitly count the terminating null character for the input string.

Note that the function always fails if the input string contains control characters (U+0001 through U+0020) or the “delete” character (U+007F). Since the character U+0000 can appear only as a terminating null character, the function always fails if U+0000 appears anywhere else in the input string.

Windows XP, Windows Server 2003: The required header file and DLL are part of the “Microsoft Internationalized Domain Name (IDN) Mitigation APIs” download, available at the MSDN Download Center.

Requirements

Header: Declared in winnls.h.

Library: Use kernelx.lib.