IdnToNameprepUnicode function (winnls.h)

Article
10/13/2021

Converts an internationalized domain name (IDN) or another internationalized label to the NamePrep form specified by Network Working Group RFC 3491, but does not perform the additional conversion to Punycode. For more information and links to related draft standards, see Handling Internationalized Domain Names (IDNs).

Syntax

int IdnToNameprepUnicode(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpUnicodeCharStr,
  [in]            int     cchUnicodeChar,
  [out, optional] LPWSTR  lpNameprepCharStr,
  [in]            int     cchNameprepChar
);

Parameters

[in] dwFlags

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

[in] lpUnicodeCharStr

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

[in] cchUnicodeChar

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

[out, optional] lpNameprepCharStr

Pointer to a buffer that receives a version of the input Unicode string converted through NamePrep processing. Alternatively, the function can retrieve NULL for this parameter, if cchNameprepChar is set to 0. In this case, the function returns the size required for this buffer.

[in] cchNameprepChar

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

Return value

Returns the number of characters retrieved in lpNameprepCharStr 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 cchNameprepChar 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.

Examples

NLS: Internationalized Domain Name (IDN) Conversion Sample demonstrates the use of this function.

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

Share via