source/include/idn2.h

0001 /* idn2.h - header file for idn2
0002    Copyright (C) 2011-2022 Simon Josefsson
0003
0004    Libidn2 is free software: you can redistribute it and/or modify it
0005    under the terms of either:
0006
0007      * the GNU Lesser General Public License as published by the Free
0008        Software Foundation; either version 3 of the License, or (at
0009        your option) any later version.
0010
0011    or
0012
0013      * the GNU General Public License as published by the Free
0014        Software Foundation; either version 2 of the License, or (at
0015        your option) any later version.
0016
0017    or both in parallel, as here.
0018
0019    This program is distributed in the hope that it will be useful,
0020    but WITHOUT ANY WARRANTY; without even the implied warranty of
0021    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0022    GNU General Public License for more details.
0023
0024    You should have received copies of the GNU General Public License and
0025    the GNU Lesser General Public License along with this program.  If
0026    not, see <http://www.gnu.org/licenses/>.
0027 */
0028
0029 #ifndef IDN2_H
0030 # define IDN2_H
0031
0032 /**
0033  * SECTION:idn2
0034  * @title: idn2.h
0035  * @short_description: main library interfaces
0036  *
0037  * The main library interfaces are declared in idn2.h.
0038  */
0039
0040 /* *INDENT-OFF* */
0041 /* see https://www.gnu.org/software/gnulib/manual/html_node/Exported-Symbols-of-Shared-Libraries.html */
0042 #ifndef _IDN2_API
0043 # if defined IDN2_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
0044 #  define _IDN2_API __attribute__((__visibility__("default")))
0045 # elif defined IDN2_BUILDING && defined _MSC_VER && ! defined IDN2_STATIC
0046 #  define _IDN2_API __declspec(dllexport)
0047 # elif defined _MSC_VER && ! defined IDN2_STATIC
0048 #  define _IDN2_API __declspec(dllimport)
0049 # else
0050 #  define _IDN2_API
0051 # endif
0052 #endif
0053 /* *INDENT-ON* */
0054
0055 # include <stdint.h>        /* uint32_t */
0056 # include <string.h>        /* size_t */
0057
0058 # ifdef __cplusplus
0059 extern "C"
0060 {
0061 # endif
0062
0063 /**
0064  * GCC_VERSION_AT_LEAST
0065  * @major: gcc major version number to compare with
0066  * @minor: gcc minor version number to compare with
0067  *
0068  * Pre-processor symbol to check the gcc version.
0069  */
0070 # if defined __GNUC__ && defined __GNUC_MINOR__
0071 #  define GCC_VERSION_AT_LEAST(major, minor) ((__GNUC__ > (major)) || (__GNUC__ == (major) && __GNUC_MINOR__ >= (minor)))
0072 # else
0073 #  define GCC_VERSION_AT_LEAST(major, minor) 0
0074 # endif
0075
0076 /* the following G_GNUC_ prefixes are for gtk-doc to recognize the attributes */
0077
0078 /**
0079  * G_GNUC_IDN2_ATTRIBUTE_PURE
0080  *
0081  * Function attribute: Function is a pure function.
0082  */
0083 # if GCC_VERSION_AT_LEAST(2,96)
0084 #  define G_GNUC_IDN2_ATTRIBUTE_PURE __attribute__ ((pure))
0085 # else
0086 #  define G_GNUC_IDN2_ATTRIBUTE_PURE
0087 # endif
0088
0089 /**
0090  * G_GNUC_IDN2_ATTRIBUTE_CONST
0091  *
0092  * Function attribute: Function is a const function.
0093  */
0094 # if GCC_VERSION_AT_LEAST(2,5)
0095 #  define G_GNUC_IDN2_ATTRIBUTE_CONST __attribute__ ((const))
0096 # else
0097 #  define G_GNUC_IDN2_ATTRIBUTE_CONST
0098 # endif
0099
0100 /**
0101  * G_GNUC_DEPRECATED
0102  *
0103  * Function attribute: Function is deprecated.
0104  */
0105 # if GCC_VERSION_AT_LEAST(3,1)
0106 #  define G_GNUC_DEPRECATED __attribute__((deprecated))
0107 # elif defined(_MSC_VER)
0108 #  define G_GNUC_DEPRECATED __declspec(deprecated)
0109 # else
0110 #  define G_GNUC_DEPRECATED /* empty */
0111 # endif
0112
0113 /**
0114  * G_GNUC_UNUSED
0115  *
0116  * Parameter attribute: Parameter is not used.
0117  */
0118 # if GCC_VERSION_AT_LEAST(2,95)
0119 #  define G_GNUC_UNUSED __attribute__ ((__unused__))
0120 # else
0121 #  define G_GNUC_UNUSED     /* empty */
0122 # endif
0123
0124
0125 /**
0126  * IDN2_VERSION
0127  *
0128  * Pre-processor symbol with a string that describe the header file
0129  * version number.  Used together with idn2_check_version() to verify
0130  * header file and run-time library consistency.
0131  */
0132 # define IDN2_VERSION "2.3.4"
0133
0134 /**
0135  * IDN2_VERSION_NUMBER
0136  *
0137  * Pre-processor symbol with a hexadecimal value describing the header
0138  * file version number.  For example, when the header version is
0139  * 1.2.4711 this symbol will have the value 0x01021267.  The last four
0140  * digits are used to enumerate development snapshots, but for all
0141  * public releases they will be 0000.
0142  */
0143 # define IDN2_VERSION_NUMBER 0x02030004
0144
0145 /**
0146  * IDN2_VERSION_MAJOR
0147  *
0148  * Pre-processor symbol for the major version number (decimal).
0149  * The version scheme is major.minor.patchlevel.
0150  */
0151 # define IDN2_VERSION_MAJOR 2
0152
0153 /**
0154  * IDN2_VERSION_MINOR
0155  *
0156  * Pre-processor symbol for the minor version number (decimal).
0157  * The version scheme is major.minor.patchlevel.
0158  */
0159 # define IDN2_VERSION_MINOR 3
0160
0161 /**
0162  * IDN2_VERSION_PATCH
0163  *
0164  * Pre-processor symbol for the patch level number (decimal).
0165  * The version scheme is major.minor.patchlevel.
0166  */
0167 # define IDN2_VERSION_PATCH 4
0168
0169 /**
0170  * IDN2_LABEL_MAX_LENGTH
0171  *
0172  * Constant specifying the maximum length of a DNS label to 63
0173  * characters, as specified in RFC 1034.
0174  */
0175 # define IDN2_LABEL_MAX_LENGTH 63
0176
0177 /**
0178  * IDN2_DOMAIN_MAX_LENGTH
0179  *
0180  * Constant specifying the maximum size of the wire encoding of a DNS
0181  * domain to 255 characters, as specified in RFC 1034.  Note that the
0182  * usual printed representation of a domain name is limited to 253
0183  * characters if it does not end with a period, or 254 characters if
0184  * it ends with a period.
0185  */
0186 # define IDN2_DOMAIN_MAX_LENGTH 255
0187
0188 /**
0189  * idn2_flags:
0190  * @IDN2_NFC_INPUT: Normalize input string using normalization form C.
0191  * @IDN2_ALABEL_ROUNDTRIP: Perform optional IDNA2008 lookup roundtrip check (default).
0192  * @IDN2_NO_ALABEL_ROUNDTRIP: Disable ALabel lookup roundtrip check.
0193  * @IDN2_NO_TR46: Disable Unicode TR46 processing.
0194  * @IDN2_TRANSITIONAL: Perform Unicode TR46 transitional processing.
0195  * @IDN2_NONTRANSITIONAL: Perform Unicode TR46 non-transitional processing (default).
0196  * @IDN2_ALLOW_UNASSIGNED: Libidn compatibility flag, unused.
0197  * @IDN2_USE_STD3_ASCII_RULES: Use STD3 ASCII rules.
0198  * This is a Unicode TR46 only flag, and will be ignored when set without
0199  * either @IDN2_TRANSITIONAL or @IDN2_NONTRANSITIONAL.
0200  *
0201  * Flags to IDNA2008 functions, to be binary or:ed together.  Specify
0202  * only 0 if you want the default behaviour.
0203  */
0204   typedef enum
0205   {
0206     IDN2_NFC_INPUT = 1,
0207     IDN2_ALABEL_ROUNDTRIP = 2,
0208     IDN2_TRANSITIONAL = 4,
0209     IDN2_NONTRANSITIONAL = 8,
0210     IDN2_ALLOW_UNASSIGNED = 16,
0211     IDN2_USE_STD3_ASCII_RULES = 32,
0212     IDN2_NO_TR46 = 64,
0213     IDN2_NO_ALABEL_ROUNDTRIP = 128
0214   } idn2_flags;
0215
0216 /* IDNA2008 with UTF-8 encoded inputs. */
0217
0218   extern _IDN2_API int
0219     idn2_lookup_u8 (const uint8_t * src, uint8_t ** lookupname, int flags);
0220
0221   extern _IDN2_API int
0222     idn2_register_u8 (const uint8_t * ulabel, const uint8_t * alabel,
0223               uint8_t ** insertname, int flags);
0224
0225 /* IDNA2008 with locale encoded inputs. */
0226
0227   extern _IDN2_API int
0228     idn2_lookup_ul (const char *src, char **lookupname, int flags);
0229
0230   extern _IDN2_API int
0231     idn2_register_ul (const char *ulabel, const char *alabel,
0232               char **insertname, int flags);
0233
0234 /**
0235  * idn2_rc:
0236  * @IDN2_OK: Successful return.
0237  * @IDN2_MALLOC: Memory allocation error.
0238  * @IDN2_NO_CODESET: Could not determine locale string encoding format.
0239  * @IDN2_ICONV_FAIL: Could not transcode locale string to UTF-8.
0240  * @IDN2_ENCODING_ERROR: Unicode data encoding error.
0241  * @IDN2_NFC: Error normalizing string.
0242  * @IDN2_PUNYCODE_BAD_INPUT: Punycode invalid input.
0243  * @IDN2_PUNYCODE_BIG_OUTPUT: Punycode output buffer too small.
0244  * @IDN2_PUNYCODE_OVERFLOW: Punycode conversion would overflow.
0245  * @IDN2_TOO_BIG_DOMAIN: Domain name longer than 255 characters.
0246  * @IDN2_TOO_BIG_LABEL: Domain label longer than 63 characters.
0247  * @IDN2_INVALID_ALABEL: Input A-label is not valid.
0248  * @IDN2_UALABEL_MISMATCH: Input A-label and U-label does not match.
0249  * @IDN2_INVALID_FLAGS: Invalid combination of flags.
0250  * @IDN2_NOT_NFC: String is not NFC.
0251  * @IDN2_2HYPHEN: String has forbidden two hyphens.
0252  * @IDN2_HYPHEN_STARTEND: String has forbidden starting/ending hyphen.
0253  * @IDN2_LEADING_COMBINING: String has forbidden leading combining character.
0254  * @IDN2_DISALLOWED: String has disallowed character.
0255  * @IDN2_CONTEXTJ: String has forbidden context-j character.
0256  * @IDN2_CONTEXTJ_NO_RULE: String has context-j character with no rull.
0257  * @IDN2_CONTEXTO: String has forbidden context-o character.
0258  * @IDN2_CONTEXTO_NO_RULE: String has context-o character with no rull.
0259  * @IDN2_UNASSIGNED: String has forbidden unassigned character.
0260  * @IDN2_BIDI: String has forbidden bi-directional properties.
0261  * @IDN2_DOT_IN_LABEL: Label has forbidden dot (TR46).
0262  * @IDN2_INVALID_TRANSITIONAL: Label has character forbidden in transitional mode (TR46).
0263  * @IDN2_INVALID_NONTRANSITIONAL: Label has character forbidden in non-transitional mode (TR46).
0264  * @IDN2_ALABEL_ROUNDTRIP_FAILED: ALabel -> Ulabel -> ALabel result differs from input.
0265  *
0266  * Return codes for IDN2 functions.  All return codes are negative
0267  * except for the successful code IDN2_OK which are guaranteed to be
0268  * 0.  Positive values are reserved for non-error return codes.
0269  *
0270  * Note that the #idn2_rc enumeration may be extended at a later date
0271  * to include new return codes.
0272  */
0273   typedef enum
0274   {
0275     IDN2_OK = 0,
0276     IDN2_MALLOC = -100,
0277     IDN2_NO_CODESET = -101,
0278     IDN2_ICONV_FAIL = -102,
0279     IDN2_ENCODING_ERROR = -200,
0280     IDN2_NFC = -201,
0281     IDN2_PUNYCODE_BAD_INPUT = -202,
0282     IDN2_PUNYCODE_BIG_OUTPUT = -203,
0283     IDN2_PUNYCODE_OVERFLOW = -204,
0284     IDN2_TOO_BIG_DOMAIN = -205,
0285     IDN2_TOO_BIG_LABEL = -206,
0286     IDN2_INVALID_ALABEL = -207,
0287     IDN2_UALABEL_MISMATCH = -208,
0288     IDN2_INVALID_FLAGS = -209,
0289     IDN2_NOT_NFC = -300,
0290     IDN2_2HYPHEN = -301,
0291     IDN2_HYPHEN_STARTEND = -302,
0292     IDN2_LEADING_COMBINING = -303,
0293     IDN2_DISALLOWED = -304,
0294     IDN2_CONTEXTJ = -305,
0295     IDN2_CONTEXTJ_NO_RULE = -306,
0296     IDN2_CONTEXTO = -307,
0297     IDN2_CONTEXTO_NO_RULE = -308,
0298     IDN2_UNASSIGNED = -309,
0299     IDN2_BIDI = -310,
0300     IDN2_DOT_IN_LABEL = -311,
0301     IDN2_INVALID_TRANSITIONAL = -312,
0302     IDN2_INVALID_NONTRANSITIONAL = -313,
0303     IDN2_ALABEL_ROUNDTRIP_FAILED = -314,
0304   } idn2_rc;
0305
0306 /* Auxiliary functions. */
0307
0308   extern _IDN2_API int
0309     idn2_to_ascii_4i (const uint32_t * input, size_t inlen, char *output,
0310               int flags) G_GNUC_DEPRECATED;
0311   extern _IDN2_API int idn2_to_ascii_4i2 (const uint32_t * input,
0312                       size_t inlen, char **output,
0313                       int flags);
0314   extern _IDN2_API int idn2_to_ascii_4z (const uint32_t * input,
0315                      char **output, int flags);
0316   extern _IDN2_API int idn2_to_ascii_8z (const char *input, char **output,
0317                      int flags);
0318   extern _IDN2_API int idn2_to_ascii_lz (const char *input, char **output,
0319                      int flags);
0320
0321   extern _IDN2_API int
0322     idn2_to_unicode_8z4z (const char *input, uint32_t ** output,
0323               int flags G_GNUC_UNUSED);
0324   extern _IDN2_API int idn2_to_unicode_4z4z (const uint32_t * input,
0325                          uint32_t ** output, int flags);
0326   extern _IDN2_API int idn2_to_unicode_44i (const uint32_t * in, size_t inlen,
0327                         uint32_t * out, size_t *outlen,
0328                         int flags);
0329   extern _IDN2_API int idn2_to_unicode_8z8z (const char *input, char **output,
0330                          int flags);
0331   extern _IDN2_API int idn2_to_unicode_8zlz (const char *input, char **output,
0332                          int flags);
0333   extern _IDN2_API int idn2_to_unicode_lzlz (const char *input, char **output,
0334                          int flags);
0335
0336   extern _IDN2_API const char *idn2_strerror (int rc)
0337     G_GNUC_IDN2_ATTRIBUTE_CONST;
0338   extern _IDN2_API const char *idn2_strerror_name (int rc)
0339     G_GNUC_IDN2_ATTRIBUTE_CONST;
0340
0341   extern _IDN2_API const char *idn2_check_version (const char *req_version)
0342     G_GNUC_IDN2_ATTRIBUTE_PURE;
0343
0344   extern _IDN2_API void idn2_free (void *ptr);
0345
0346 # ifndef __GTK_DOC_IGNORE__
0347 /*** libidn compatibility layer ***/
0348 #  if !defined IDNA_H && !defined IDN2_SKIP_LIBIDN_COMPAT
0349
0350 /**
0351  * Idna_rc:
0352  * @IDNA_SUCCESS: Same as %IDN2_OK
0353  * @IDNA_STRINGPREP_ERROR: Same as %IDN2_ENCODING_ERROR
0354  * @IDNA_PUNYCODE_ERROR: Same as %IDN2_PUNYCODE_BAD_INPUT
0355  * @IDNA_CONTAINS_NON_LDH: Same as %IDN2_ENCODING_ERROR
0356  * @IDNA_CONTAINS_LDH: Same as %IDNA_CONTAINS_NON_LDH
0357  * @IDNA_CONTAINS_MINUS: Same as %IDN2_ENCODING_ERROR
0358  * @IDNA_INVALID_LENGTH: Same as %IDN2_DISALLOWED
0359  * @IDNA_NO_ACE_PREFIX: Same as %IDN2_ENCODING_ERROR
0360  * @IDNA_ROUNDTRIP_VERIFY_ERROR: Same as %IDN2_ENCODING_ERROR
0361  * @IDNA_CONTAINS_ACE_PREFIX: Same as %IDN2_ENCODING_ERROR
0362  * @IDNA_ICONV_ERROR: Same as %IDN2_ENCODING_ERROR
0363  * @IDNA_MALLOC_ERROR: Same as %IDN2_MALLOC
0364  * @IDNA_DLOPEN_ERROR: Same as %IDN2_MALLOC
0365  *
0366  * Return codes for transition to / compatibility with libidn2.
0367  *
0368  * Please be aware that return codes from idna_ functions might be unexpected
0369  * when linked / built with libidn2.
0370  */
0371   typedef enum
0372   {
0373     IDNA_SUCCESS = IDN2_OK,
0374     IDNA_STRINGPREP_ERROR = IDN2_ENCODING_ERROR,
0375     IDNA_PUNYCODE_ERROR = IDN2_PUNYCODE_BAD_INPUT,
0376     IDNA_CONTAINS_NON_LDH = IDN2_ENCODING_ERROR,
0377     IDNA_CONTAINS_LDH = IDNA_CONTAINS_NON_LDH,
0378     IDNA_CONTAINS_MINUS = IDN2_ENCODING_ERROR,
0379     IDNA_INVALID_LENGTH = IDN2_DISALLOWED,
0380     IDNA_NO_ACE_PREFIX = IDN2_ENCODING_ERROR,
0381     IDNA_ROUNDTRIP_VERIFY_ERROR = IDN2_ENCODING_ERROR,
0382     IDNA_CONTAINS_ACE_PREFIX = IDN2_ENCODING_ERROR,
0383     IDNA_ICONV_ERROR = IDN2_ENCODING_ERROR,
0384     IDNA_MALLOC_ERROR = IDN2_MALLOC,
0385     IDNA_DLOPEN_ERROR = IDN2_MALLOC
0386   } Idna_rc;
0387
0388 /**
0389  * Idna_flags:
0390  * @IDNA_ALLOW_UNASSIGNED: Same as %IDN2_ALLOW_UNASSIGNED
0391  * @IDNA_USE_STD3_ASCII_RULES: Same as %IDN2_USE_STD3_ASCII_RULES
0392  *
0393  * Flags for transition to / compatibility with libidn2.
0394  */
0395   typedef enum
0396   {
0397     IDNA_ALLOW_UNASSIGNED = IDN2_ALLOW_UNASSIGNED,
0398     IDNA_USE_STD3_ASCII_RULES = IDN2_USE_STD3_ASCII_RULES
0399   } Idna_flags;
0400
0401 #   define idna_to_ascii_4i(i,l,o,f)  idn2_to_ascii_4i(i,l,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0402 #   define idna_to_ascii_4z(i,o,f)  idn2_to_ascii_4z(i,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0403 #   define idna_to_ascii_8z(i,o,f)  idn2_to_ascii_8z(i,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0404 #   define idna_to_ascii_lz(i,o,f)  idn2_to_ascii_lz(i,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0405
0406 #   define idna_to_unicode_8z4z  idn2_to_unicode_8z4z
0407 #   define idna_to_unicode_4z4z  idn2_to_unicode_4z4z
0408 #   define idna_to_unicode_44i   idn2_to_unicode_44i
0409 #   define idna_to_unicode_8z8z  idn2_to_unicode_8z8z
0410 #   define idna_to_unicode_8zlz  idn2_to_unicode_8zlz
0411 #   define idna_to_unicode_lzlz  idn2_to_unicode_lzlz
0412
0413 #   define idna_strerror         idn2_strerror
0414 #   define idn_free              idn2_free
0415
0416 #  endif            /* IDNA_H */
0417 # endif
0418
0419 # ifdef __cplusplus
0420 }
0421 # endif
0422
0423 #endif              /* IDN2_H */