libidn2: Converting from libidn

 
 3 Converting from libidn
 ************************
 
 This library is backwards (API) compatible with the libidn library
 (<https://www.gnu.org/software/libidn/>).
 
    Although it is recommended for new software to use the native libidn2
 functions (i.e., the ones prefixed with ‘idn2’), old software isn’t
 always feasible to modify.
 
 3.1 Converting with minimal modifications
 =========================================
 
 As such, libidn2, provides compatibility macros which switch all libidn
 functions, to libidn2 functions in a backwards compatible way.  To take
 advantage of these compatibility functions, it is sufficient to replace
 the ‘idna.h’ header in legacy code, with ‘idn2.h’.  That would transform
 the software from using libidn, i.e., IDNA2003, to using libidn2 with
 IDNA2008 non-transitional encoding.
 
 3.2 Converting to native APIs
 =============================
 
 However, it is recommended to switch applications to the IDN2 native
 APIs.  The following table provides a mapping of libidn code snippets to
 libidn2, for switching to IDNA2008.
 
 libidn                        libidn2
                               
 ------------------------------------------------------------
 rc = idna_to_ascii_8z (buf, &p, 0 /* any flags */);rc = idn2_to_ascii_8z (buf, &p, IDN2_NONTRANSITIONAL);
 if (rc != IDNA_SUCCESS)       if (rc != IDN2_OK)
                               
 rc = idna_to_unicode_8z8z (buf, &p, 0 /* any flags */);rc = idn2_to_unicode_8z8z (buf, &p, 0);
 if (rc != IDNA_SUCCESS)       if (rc != IDN2_OK)
                               
 
    Note that, although the table only lists the UTF-8 functions, the
 mapping is identical for every other one on the family of toUnicode and
 toAscii.  As the IDNA2003 details differ signicantly to IDNA2008, no
 flags used in the libidn functions map to any specific flags; it is safe
 to use the suggested libidn2 flags.
 
 3.3 Converting with backwards compatibility
 ===========================================
 
 In several cases where IDNA2008 mappings do not exist whereas IDNA2003
 mappings do, software like browsers take a backwards compatible
 approach.  That is convert the domain to IDNA2008 form, and if that
 fails try the IDNA2003 conversion.  The following example demonstrates
 that approach.
 
 rc = idn2_to_ascii_8z (buf, &p, IDN2_NONTRANSITIONAL); /* IDNA2008 */
 if (rc == IDN2_DISALLOWED)
   rc = idn2_to_ascii_8z (buf, &p, IDN2_TRANSITIONAL); /* IDNA2003 - compatible */
 
 3.4 Using libidn and libidn2 code
 =================================
 
 In the special case of software that needs to support both libraries
 (e.g., both IDNA2003 and IDNA2008), you must define
 ‘IDN2_SKIP_LIBIDN_COMPAT’ prior to including ‘idn2.h’ in order to be
 able to use both libraries’ functions.