Tizen(Headed) Native API  6.5

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

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).

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]optionsBit set to modify the processing and error checking. See i18n_uidna_option_e for options.
[out]uidnaThe UTS #46 UIDNA instance, if successful
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
See also:
i18n_uidna_destroy

Destroys a UIDNA instance.

Since :
6.0
Parameters:
[in]uidnaUIDNA instance to be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_uidna_create

Destroys a UIDNA info handle.

Since :
6.0
Parameters:
[in]infoThe UIDNA info handle to be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]infoUIDNA info handle
[out]errorsBit 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]infoUIDNA info handle
[out]is_trans_differentTRUE if transitional and nontransitional processing produce different results.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]uidnaA UIDNA instance
[in]labelInput domain name label
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]uidnaA UIDNA instance
[in]labelInput domain name label
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]uidnaA UIDNA instance
[in]labelInput domain name label
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]uidnaA UIDNA instance
[in]labelInput domain name label
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]uidnaA UIDNA instance
[in]nameInput domain name
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]uidnaA UIDNA instance
[in]nameInput domain name
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]uidnaA UIDNA instance
[in]nameInput domain name
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]uidnaA UIDNA instance
[in]nameInput domain name
[in]lengthLabel length, or -1 if NUL-terminated
[in]destDestination string buffer
[in]capacityDestination buffer capacity
[out]infoOutput container of IDNA processing details.
[out]lenDestination string length
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory