Uidna module provides Internationalizing Domain Names in Applications.

Required Header

#include <utils_i18n.h>

Functions
int	i18n_uidna_create (uint32_t options, i18n_uidna_h *uidna)
	Returns a UIDNA instance which implements UTS #46.
int	i18n_uidna_destroy (i18n_uidna_h uidna)
	Destroys a UIDNA instance.
int	i18n_uidna_label_to_ascii (i18n_uidna_h uidna, const i18n_uchar label, int32_t length, i18n_uchar dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a single domain name label into its ASCII form for DNS lookup.
int	i18n_uidna_label_to_unicode (i18n_uidna_h uidna, const i18n_uchar label, int32_t length, i18n_uchar dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a single domain name label into its Unicode form for human-readable display.
int	i18n_uidna_name_to_ascii (i18n_uidna_h uidna, const i18n_uchar name, int32_t length, i18n_uchar dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a whole domain name into its ASCII form for DNS lookup.
int	i18n_uidna_name_to_unicode (i18n_uidna_h uidna, const i18n_uchar name, int32_t length, i18n_uchar dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a whole domain name into its Unicode form for human-readable display.
int	i18n_uidna_label_to_ascii_UTF8 (i18n_uidna_h uidna, const char label, int32_t length, char dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a single domain name label (UTF8 encoded) into its ASCII form for DNS lookup.
int	i18n_uidna_label_to_unicode_UTF8 (i18n_uidna_h uidna, const char label, int32_t length, char dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a single domain name label into its Unicode form for human-readable display.
int	i18n_uidna_name_to_ascii_UTF8 (i18n_uidna_h uidna, const char name, int32_t length, char dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a whole domain name into its ASCII form for DNS lookup.
int	i18n_uidna_name_to_unicode_UTF8 (i18n_uidna_h uidna, const char name, int32_t length, char dest, int32_t capacity, i18n_uidna_info_h info, int32_t len)
	Converts a whole domain name into its Unicode form for human-readable display.
int	i18n_uidna_info_get_is_trans_different (i18n_uidna_info_h info, i18n_ubool *is_trans_different)
	Gets whether transitional and nontransitional processing produce different results.
int	i18n_uidna_info_get_errors (i18n_uidna_info_h info, uint32_t *errors)
	Gets the bit set indicating UIDNA processing errors.
int	i18n_uidna_info_destroy (i18n_uidna_info_h info)
	Destroys a UIDNA info handle.
Typedefs
typedef void *	i18n_uidna_h
	An i18n_uidna_h handle.
typedef void *	i18n_uidna_info_h
	An i18n_uidna_info_h handle.

Typedef Documentation

typedef void* i18n_uidna_h

An i18n_uidna_h handle.

Use i18n_uidna_* functions to operate on i18n_uidna_h objects.

Since :: 6.0

typedef void* i18n_uidna_info_h

An i18n_uidna_info_h handle.

Since :: 6.0

Enumeration Type Documentation

enum i18n_uidna_error_e

UIDNA error bit set values.

When a domain name or label fails a processing step or does not meet the validity criteria, then one or more of these error bits are set.

Since :: 6.0

Enumerator:

I18N_UIDNA_ERROR_NONE	No errors
I18N_UIDNA_ERROR_EMPTY_LABEL	A non-final domain name label (or the whole domain name) is empty.
I18N_UIDNA_ERROR_LABEL_TOO_LONG	A domain name label is longer than 63 bytes. (See STD13/RFC1034 3.1. Name space specifications and terminology.) This is only checked in ToASCII operations, and only if the output label is all-ASCII.
I18N_UIDNA_ERROR_DOMAIN_NAME_TOO_LONG	A domain name is longer than 255 bytes in its storage form. (See STD13/RFC1034 3.1. Name space specifications and terminology.) This is only checked in ToASCII operations, and only if the output domain name is all-ASCII.
I18N_UIDNA_ERROR_LEADING_HYPHEN	A label starts with a hyphen-minus ('-').
I18N_UIDNA_ERROR_TRAILING_HYPHEN	A label ends with a hyphen-minus ('-').
I18N_UIDNA_ERROR_HYPHEN_3_4	A label contains hyphen-minus ('-') in the third and fourth positions.
I18N_UIDNA_ERROR_LEADING_COMBINING_MARK	A label starts with a combining mark.
I18N_UIDNA_ERROR_DISALLOWED	A label or domain name contains disallowed characters.
I18N_UIDNA_ERROR_PUNYCODE	A label starts with "xn--" but does not contain valid Punycode. That is, an xn? label failed Punycode decoding.
I18N_UIDNA_ERROR_LABEL_HAS_DOT	A label contains a dot=full stop. This can occur in an input string for a single-label function.
I18N_UIDNA_ERROR_INVALID_ACE_LABEL	An ACE label does not contain a valid label string. The label was successfully ACE (Punycode) decoded but the resulting string had severe validation errors. For example, it might contain characters that are not allowed in ACE labels, or it might not be normalized.
I18N_UIDNA_ERROR_BIDI	A label does not meet the IDNA BiDi requirements (for right-to-left characters).
I18N_UIDNA_ERROR_CONTEXTJ	A label does not meet the IDNA CONTEXTJ requirements.
I18N_UIDNA_ERROR_CONTEXTO_PUNCTUATION	A label does not meet the IDNA CONTEXTO requirements for punctuation characters. Some punctuation characters "Would otherwise have been DISALLOWED" but are allowed in certain contexts. (RFC 5892)
I18N_UIDNA_ERROR_CONTEXTO_DIGITS	A label does not meet the IDNA CONTEXTO requirements for digits. Arabic-Indic Digits (U+066x) must not be mixed with Extended Arabic-Indic Digits (U+06Fx).

enum i18n_uidna_option_e

IDNA option bit set values.

Since :: 6.0

Enumerator:

I18N_UIDNA_DEFAULT	Default options value: None of the other options are set. For use in static worker and factory methods.
I18N_UIDNA_USE_STD3_RULES	Option to check whether the input conforms to the STD3 ASCII rules, for example the restriction of labels to LDH characters(ASCII Letters, Digits and Hyphen-Minus). For use in static worker and factory methods.
I18N_UIDNA_CHECK_BIDI	IDNA option to check for whether the input conforms to the BiDi rules. For use in static worker and factory methods. This option is ignored by the IDNA2003 implementation.(IDNA2003 always performs a BiDi check.)
I18N_UIDNA_CHECK_CONTEXTJ	IDNA option to check for whether the input conforms to the CONTEXTJ rules. For use in static worker and factory methods. This option is ignored by the IDNA2003 implementation.(CONTEXTJ check is new in IDNA2008.)
I18N_UIDNA_NONTRANSITIONAL_TO_ASCII	IDNA option for nontransitional processing i18n_uidna__to_ascii(). For use in static worker and factory methods. By default, i18n_uidna__to_ascii() uses transitional processing. This option is ignored by the IDNA2003 implementation. (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.)
I18N_UIDNA_NONTRANSITIONAL_TO_UNICODE	IDNA option for nontransitional processing in i18n_uidna__to_unicode(). For use in static worker and factory methods. By default, i18n_uidna__to_unicode() uses transitional processing. This option is ignored by the IDNA2003 implementation. (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.)
I18N_UIDNA_CHECK_CONTEXTO	IDNA option to check for whether the input conforms to the CONTEXTO rules. For use in static worker and factory methods. This option is ignored by the IDNA2003 implementation.(The CONTEXTO check is new in IDNA2008.) This is for use by registries for IDNA2008 conformance. UTS #46 does not require the CONTEXTO check.

Function Documentation

int i18n_uidna_create	(	uint32_t	options,
		i18n_uidna_h *	uidna
	)

Returns a UIDNA instance which implements UTS #46.

Returns an unmodifiable instance, owned by the caller. Cache it for multiple operations, and i18n_uidna_destroy() it when done. The instance is thread-safe, that is, it can be used concurrently.

Since :: 6.0

Remarks:: The uidna should be released using i18n_uidna_destroy().

Parameters:

[in]	options	Bit set to modify the processing and error checking. See i18n_uidna_option_e for options.
[out]	uidna	The UTS #46 UIDNA instance, if successful

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

See also:: i18n_uidna_destroy

int i18n_uidna_destroy ( i18n_uidna_h uidna )

Destroys a UIDNA instance.

Since :: 6.0

Parameters:

[in] uidna UIDNA instance to be destroyed

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_uidna_create

int i18n_uidna_info_destroy ( i18n_uidna_info_h info )

Destroys a UIDNA info handle.

Since :: 6.0

Parameters:

[in] info The UIDNA info handle to be destroyed

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_uidna_info_get_errors	(	i18n_uidna_info_h	info,
		uint32_t *	errors
	)

Gets the bit set indicating UIDNA processing errors.

Since :: 6.0

Parameters:

[in]	info	UIDNA info handle
[out]	errors	Bit set with UIDNA processing errors 0 if no errors, see i18n_uidna_error_e

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_uidna_info_get_is_trans_different	(	i18n_uidna_info_h	info,
		i18n_ubool *	is_trans_different
	)

Gets whether transitional and nontransitional processing produce different results.

Since :: 6.0

Parameters:

[in]	info	UIDNA info handle
[out]	is_trans_different	TRUE if transitional and nontransitional processing produce different results.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_uidna_label_to_ascii	(	i18n_uidna_h	uidna,
		const i18n_uchar *	label,
		int32_t	length,
		i18n_uchar *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a single domain name label into its ASCII form for DNS lookup.

The label might be modified according to the types of errors. Labels with severe errors will be left in (or turned into) their Unicode form. The i18n_error_code_e indicates an error only in exceptional cases, such as a I18N_ERROR_OUT_OF_MEMORY.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	label	Input domain name label
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_uidna_label_to_ascii_UTF8	(	i18n_uidna_h	uidna,
		const char *	label,
		int32_t	length,
		char *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a single domain name label (UTF8 encoded) into its ASCII form for DNS lookup.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	label	Input domain name label
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_uidna_label_to_unicode	(	i18n_uidna_h	uidna,
		const i18n_uchar *	label,
		int32_t	length,
		i18n_uchar *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a single domain name label into its Unicode form for human-readable display.

The i18n_error_code_e indicates an error only in exceptional cases, such as a I18N_ERROR_OUT_OF_MEMORY.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	label	Input domain name label
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_uidna_label_to_unicode_UTF8	(	i18n_uidna_h	uidna,
		const char *	label,
		int32_t	length,
		char *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a single domain name label into its Unicode form for human-readable display.

UTF-8 version of i18n_uidna_label_to_unicode(), same behavior.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	label	Input domain name label
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_uidna_name_to_ascii	(	i18n_uidna_h	uidna,
		const i18n_uchar *	name,
		int32_t	length,
		i18n_uchar *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a whole domain name into its ASCII form for DNS lookup.

The domain name might be modified according to the types of errors. Labels with severe errors will be left in (or turned into) their Unicode form. The i18n_error_code_e indicates an error only in exceptional cases, such as a I18N_ERROR_OUT_OF_MEMORY.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	name	Input domain name
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_uidna_name_to_ascii_UTF8	(	i18n_uidna_h	uidna,
		const char *	name,
		int32_t	length,
		char *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a whole domain name into its ASCII form for DNS lookup.

UTF-8 version of i18n_uidna_name_to_ascii(), same behavior.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	name	Input domain name
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_uidna_name_to_unicode	(	i18n_uidna_h	uidna,
		const i18n_uchar *	name,
		int32_t	length,
		i18n_uchar *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a whole domain name into its Unicode form for human-readable display.

The i18n_error_code_e indicates an error only in exceptional cases, such as a I18N_ERROR_OUT_OF_MEMORY.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	name	Input domain name
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_uidna_name_to_unicode_UTF8	(	i18n_uidna_h	uidna,
		const char *	name,
		int32_t	length,
		char *	dest,
		int32_t	capacity,
		i18n_uidna_info_h *	info,
		int32_t *	len
	)

Converts a whole domain name into its Unicode form for human-readable display.

UTF-8 version of i18n_uidna_name_to_unicode(), same behavior.

Since :: 6.0

Remarks:: info should be released with i18n_uidna_info_destroy().

Parameters:

[in]	uidna	A UIDNA instance
[in]	name	Input domain name
[in]	length	Label length, or -1 if NUL-terminated
[in]	dest	Destination string buffer
[in]	capacity	Destination buffer capacity
[out]	info	Output container of IDNA processing details.
[out]	len	Destination string length

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

Required Header

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation