Next: Converting from libidn, Previous: Introduction, Up: Libidn2 [Contents][Index]
Below are the interfaces of the Libidn2 library documented.
idn2.hidn2.hTo use the functions documented in this chapter, you need to include the file idn2.h like this:
#include <idn2.h>
When you have the data encoded in UTF-8 form the direct interfaces to the library are as follows.
input: zero terminated input UTF-8 string.
output: pointer to newly allocated output string.
flags: optional idn2_flags to modify behaviour.
Convert UTF-8 domain name to ASCII string using the IDNA2008 rules. The domain name may contain several labels, separated by dots. The output buffer must be deallocated by the caller.
The default behavior of this function (when flags are zero) is to apply
the IDNA2008 rules without the TR46 amendments. As the TR46
non-transitional processing is nowadays ubiquitous, when unsure, it is
recommended to call this function with the IDN2_NONTRANSITIONAL
and the IDN2_NFC_INPUT flags for compatibility with other software.
Return value: Returns IDN2_OK on success, or error code.
Since: 2.0.0
input: Input zero-terminated UTF-8 string.
output: Newly allocated UTF-8 output string.
flags: Currently unused.
Converts a possibly ACE encoded domain name in UTF-8 format into a UTF-8 string (punycode decoding). The output buffer will be zero-terminated and must be deallocated by the caller.
output may be NULL to test lookup of input without allocating memory.
Since: 2.0.0
src: input zero-terminated UTF-8 string in Unicode NFC normalized form.
lookupname: newly allocated output variable with name to lookup in DNS.
flags: optional idn2_flags to modify behaviour.
Perform IDNA2008 lookup string conversion on domain name src , as
described in section 5 of RFC 5891. Note that the input string
must be encoded in UTF-8 and be in Unicode NFC form.
Pass IDN2_NFC_INPUT in flags to convert input to NFC form before
further processing. IDN2_TRANSITIONAL and IDN2_NONTRANSITIONAL
do already imply IDN2_NFC_INPUT .
Pass IDN2_ALABEL_ROUNDTRIP in flags to
convert any input A-labels to U-labels and perform additional
testing. This is default since version 2.2.
To switch this behavior off, pass IDN2_NO_ALABEL_ROUNDTRIP
Pass IDN2_TRANSITIONAL to enable Unicode TR46
transitional processing, and IDN2_NONTRANSITIONAL to enable
Unicode TR46 non-transitional processing.
Multiple flags may be specified by binary or:ing them together.
After version 2.0.3: IDN2_USE_STD3_ASCII_RULES disabled by default.
Previously we were eliminating non-STD3 characters from domain strings
such as _443._tcp.example.com, or IPs 1.2.3.4/24 provided to libidn2
functions. That was an unexpected regression for applications switching
from libidn and thus it is no longer applied by default.
Use IDN2_USE_STD3_ASCII_RULES to enable that behavior again.
After version 0.11: lookupname may be NULL to test lookup of src without allocating memory.
Returns: On successful conversion IDN2_OK is returned, if the
output domain or any label would have been too long
IDN2_TOO_BIG_DOMAIN or IDN2_TOO_BIG_LABEL is returned, or
another error code is returned.
Since: 0.1
ulabel: input zero-terminated UTF-8 and Unicode NFC string, or NULL.
alabel: input zero-terminated ACE encoded string (xn–), or NULL.
insertname: newly allocated output variable with name to register in DNS.
flags: optional idn2_flags to modify behaviour.
Perform IDNA2008 register string conversion on domain label ulabel and alabel , as described in section 4 of RFC 5891. Note that the
input ulabel must be encoded in UTF-8 and be in Unicode NFC form.
Pass IDN2_NFC_INPUT in flags to convert input ulabel to NFC form
before further processing.
It is recommended to supply both ulabel and alabel for better
error checking, but supplying just one of them will work. Passing
in only alabel is better than only ulabel . See RFC 5891 section
4 for more information.
After version 0.11: insertname may be NULL to test conversion of src without allocating memory.
Returns: On successful conversion IDN2_OK is returned, when the
given ulabel and alabel does not match each other
IDN2_UALABEL_MISMATCH is returned, when either of the input
labels are too long IDN2_TOO_BIG_LABEL is returned, when alabel does does not appear to be a proper A-label IDN2_INVALID_ALABEL
is returned, or another error code is returned.
As a convenience, the following functions are provided that will convert the input from the locale encoding format to UTF-8 and normalize the string using NFC, and then apply the core functions described earlier.
input: zero terminated input UTF-8 string.
output: pointer to newly allocated output string.
flags: optional idn2_flags to modify behaviour.
Convert a domain name in locale’s encoding to ASCII string using the IDNA2008 rules. The domain name may contain several labels, separated by dots. The output buffer must be deallocated by the caller.
The default behavior of this function (when flags are zero) is to apply
the IDNA2008 rules without the TR46 amendments. As the TR46
non-transitional processing is nowadays ubiquitous, when unsure, it is
recommended to call this function with the IDN2_NONTRANSITIONAL
and the IDN2_NFC_INPUT flags for compatibility with other software.
Returns: IDN2_OK on success, or error code.
Same as described in idn2_lookup_ul() documentation.
Since: 2.0.0
input: Input zero-terminated UTF-8 string.
output: Newly allocated output string in current locale’s character set.
flags: Currently unused.
Converts a possibly ACE encoded domain name in UTF-8 format into a string encoded in the current locale’s character set (punycode decoding). The output buffer will be zero-terminated and must be deallocated by the caller.
output may be NULL to test lookup of input without allocating memory.
Since: 2.0.0
input: Input zero-terminated string encoded in the current locale’s character set.
output: Newly allocated output string in current locale’s character set.
flags: Currently unused.
Converts a possibly ACE encoded domain name in the locale’s character set into a string encoded in the current locale’s character set (punycode decoding). The output buffer will be zero-terminated and must be deallocated by the caller.
output may be NULL to test lookup of input without allocating memory.
Since: 2.0.0
src: input zero-terminated locale encoded string.
lookupname: newly allocated output variable with name to lookup in DNS.
flags: optional idn2_flags to modify behaviour.
Perform IDNA2008 lookup string conversion on domain name src , as
described in section 5 of RFC 5891. Note that the input is assumed
to be encoded in the locale’s default coding system, and will be
transcoded to UTF-8 and NFC normalized by this function.
Pass IDN2_ALABEL_ROUNDTRIP in flags to
convert any input A-labels to U-labels and perform additional
testing. This is default since version 2.2.
To switch this behavior off, pass IDN2_NO_ALABEL_ROUNDTRIP
Pass IDN2_TRANSITIONAL to enable Unicode TR46 transitional processing,
and IDN2_NONTRANSITIONAL to enable Unicode TR46 non-transitional
processing.
Multiple flags may be specified by binary or:ing them together, for
example IDN2_ALABEL_ROUNDTRIP | IDN2_NONTRANSITIONAL .
The IDN2_NFC_INPUT in flags is always enabled in this function.
After version 0.11: lookupname may be NULL to test lookup of src without allocating memory.
Returns: On successful conversion IDN2_OK is returned, if
conversion from locale to UTF-8 fails then IDN2_ICONV_FAIL is
returned, if the output domain or any label would have been too
long IDN2_TOO_BIG_DOMAIN or IDN2_TOO_BIG_LABEL is returned, or
another error code is returned.
Since: 0.1
ulabel: input zero-terminated locale encoded string, or NULL.
alabel: input zero-terminated ACE encoded string (xn–), or NULL.
insertname: newly allocated output variable with name to register in DNS.
flags: optional idn2_flags to modify behaviour.
Perform IDNA2008 register string conversion on domain label ulabel and alabel , as described in section 4 of RFC 5891. Note that the
input ulabel is assumed to be encoded in the locale’s default
coding system, and will be transcoded to UTF-8 and NFC normalized
by this function.
It is recommended to supply both ulabel and alabel for better
error checking, but supplying just one of them will work. Passing
in only alabel is better than only ulabel . See RFC 5891 section
4 for more information.
After version 0.11: insertname may be NULL to test conversion of src without allocating memory.
Returns: On successful conversion IDN2_OK is returned, when the
given ulabel and alabel does not match each other
IDN2_UALABEL_MISMATCH is returned, when either of the input
labels are too long IDN2_TOO_BIG_LABEL is returned, when alabel does does not appear to be a proper A-label IDN2_INVALID_ALABEL
is returned, when ulabel locale to UTF-8 conversion failed
IDN2_ICONV_FAIL is returned, or another error code is returned.
The flags parameter can take on the following values, or a
bit-wise inclusive or of any subset of the parameters:
Apply NFC normalization on input.
Apply additional round-trip conversion of A-label inputs.
Perform Unicode TR46 transitional processing.
Perform Unicode TR46 non-transitional processing (default).
Disable any TR#46 transitional or non-transitional processing.
Use STD3 ASCII rules. This is a TR#46 flag and is a no-op when IDN2_NO_TR46 is specified.
rc: return code from another libidn2 function.
Convert internal libidn2 error code to a humanly readable string. The returned pointer must not be de-allocated by the caller.
Return value: A humanly readable string describing error.
rc: return code from another libidn2 function.
Convert internal libidn2 error code to a string corresponding to internal header file symbols. For example, idn2_strerror_name(IDN2_MALLOC) will return the string "IDN2_MALLOC".
The caller must not attempt to de-allocate the returned string.
Return value: A string corresponding to error code symbol.
The functions normally return 0 on success or a negative error code.
Successful return.
Memory allocation error.
Could not determine locale string encoding format.
Could not transcode locale string to UTF-8.
Unicode data encoding error.
Error normalizing string.
Punycode invalid input.
Punycode output buffer too small.
Punycode conversion would overflow.
Domain name longer than 255 characters.
Domain label longer than 63 characters.
Input A-label is not valid.
Input A-label and U-label does not match.
Invalid combination of flags.
String is not NFC.
String has forbidden two hyphens.
String has forbidden starting/ending hyphen.
String has forbidden leading combining character.
String has disallowed character.
String has forbidden context-j character.
String has context-j character with no rull.
String has forbidden context-o character.
String has context-o character with no rull.
String has forbidden unassigned character.
String has forbidden bi-directional properties.
Label has forbidden dot (TR46).
Label has character forbidden in transitional mode (TR46).
Label has character forbidden in non-transitional mode (TR46).
ptr: pointer to deallocate
Call free(3) on the given pointer.
This function is typically only useful on systems where the library malloc heap is different from the library caller malloc heap, which happens on Windows when the library is a separate DLL.
It is often desirable to check that the version of Libidn2 used is indeed one which fits all requirements. Even with binary compatibility new features may have been introduced but due to problem with the dynamic linker an old version is actually used. So you may want to check that the version is okay right after program startup.
req_version: version string to compare with, or NULL.
Check IDN2 library version. This function can also be used to read
out the version of the library code used. See IDN2_VERSION for a
suitable req_version string, it corresponds to the idn2.h header
file version. Normally these two version numbers match, but if you
are using an application built against an older libidn2 with a
newer libidn2 shared library they will be different.
Return value: Check that the version of the library is at
minimum the one given as a string in req_version and return the
actual version string of the library; return NULL if the
condition is not met. If NULL is passed to this function no
check is done and only the version string is returned.
The normal way to use the function is to put something similar to the
following first in your main:
if (!idn2_check_version (IDN2_VERSION))
{
printf ("idn2_check_version() failed:\n"
"Header file incompatible with shared library.\n");
exit(EXIT_FAILURE);
}
Next: Converting from libidn, Previous: Introduction, Up: Libidn2 [Contents][Index]