source/include/idn2.h

0001 /* idn2.h - header file for idn2
0002    Copyright (C) 2011-2024 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_UNUSED
0102  *
0103  * Parameter attribute: Parameter is not used.
0104  */
0105 # if GCC_VERSION_AT_LEAST(2,95)
0106 #  define G_GNUC_UNUSED __attribute__ ((__unused__))
0107 # else
0108 #  define G_GNUC_UNUSED     /* empty */
0109 # endif
0110
0111
0112 /**
0113  * IDN2_VERSION
0114  *
0115  * Pre-processor symbol with a string that describe the header file
0116  * version number.  Used together with idn2_check_version() to verify
0117  * header file and run-time library consistency.
0118  */
0119 # define IDN2_VERSION "2.3.7"
0120
0121 /**
0122  * IDN2_VERSION_NUMBER
0123  *
0124  * Pre-processor symbol with a hexadecimal value describing the header
0125  * file version number.  For example, when the header version is
0126  * 1.2.4711 this symbol will have the value 0x01021267.  The last four
0127  * digits are used to enumerate development snapshots, but for all
0128  * public releases they will be 0000.
0129  */
0130 # define IDN2_VERSION_NUMBER 0x02030007
0131
0132 /**
0133  * IDN2_VERSION_MAJOR
0134  *
0135  * Pre-processor symbol for the major version number (decimal).
0136  * The version scheme is major.minor.patchlevel.
0137  */
0138 # define IDN2_VERSION_MAJOR 2
0139
0140 /**
0141  * IDN2_VERSION_MINOR
0142  *
0143  * Pre-processor symbol for the minor version number (decimal).
0144  * The version scheme is major.minor.patchlevel.
0145  */
0146 # define IDN2_VERSION_MINOR 3
0147
0148 /**
0149  * IDN2_VERSION_PATCH
0150  *
0151  * Pre-processor symbol for the patch level number (decimal).
0152  * The version scheme is major.minor.patchlevel.
0153  */
0154 # define IDN2_VERSION_PATCH 7
0155
0156 /**
0157  * IDN2_LABEL_MAX_LENGTH
0158  *
0159  * Constant specifying the maximum length of a DNS label to 63
0160  * characters, as specified in RFC 1034.
0161  */
0162 # define IDN2_LABEL_MAX_LENGTH 63
0163
0164 /**
0165  * IDN2_DOMAIN_MAX_LENGTH
0166  *
0167  * Constant specifying the maximum size of the wire encoding of a DNS
0168  * domain to 255 characters, as specified in RFC 1034.  Note that the
0169  * usual printed representation of a domain name is limited to 253
0170  * characters if it does not end with a period, or 254 characters if
0171  * it ends with a period.
0172  */
0173 # define IDN2_DOMAIN_MAX_LENGTH 255
0174
0175 /**
0176  * idn2_flags:
0177  * @IDN2_NFC_INPUT: Normalize input string using normalization form C.
0178  * @IDN2_ALABEL_ROUNDTRIP: Perform optional IDNA2008 lookup roundtrip check (default).
0179  * @IDN2_NO_ALABEL_ROUNDTRIP: Disable ALabel lookup roundtrip check.
0180  * @IDN2_NO_TR46: Disable Unicode TR46 processing.
0181  * @IDN2_TRANSITIONAL: Perform Unicode TR46 transitional processing.
0182  * @IDN2_NONTRANSITIONAL: Perform Unicode TR46 non-transitional processing (default).
0183  * @IDN2_ALLOW_UNASSIGNED: Libidn compatibility flag, unused.
0184  * @IDN2_USE_STD3_ASCII_RULES: Use STD3 ASCII rules.
0185  * This is a Unicode TR46 only flag, and will be ignored when set without
0186  * either @IDN2_TRANSITIONAL or @IDN2_NONTRANSITIONAL.
0187  *
0188  * Flags to IDNA2008 functions, to be binary or:ed together.  Specify
0189  * only 0 if you want the default behaviour.
0190  */
0191   typedef enum
0192   {
0193     IDN2_NFC_INPUT = 1,
0194     IDN2_ALABEL_ROUNDTRIP = 2,
0195     IDN2_TRANSITIONAL = 4,
0196     IDN2_NONTRANSITIONAL = 8,
0197     IDN2_ALLOW_UNASSIGNED = 16,
0198     IDN2_USE_STD3_ASCII_RULES = 32,
0199     IDN2_NO_TR46 = 64,
0200     IDN2_NO_ALABEL_ROUNDTRIP = 128
0201   } idn2_flags;
0202
0203 /* IDNA2008 with UTF-8 encoded inputs. */
0204
0205   extern _IDN2_API int
0206     idn2_lookup_u8 (const uint8_t * src, uint8_t ** lookupname, int flags);
0207
0208   extern _IDN2_API int
0209     idn2_register_u8 (const uint8_t * ulabel, const uint8_t * alabel,
0210               uint8_t ** insertname, int flags);
0211
0212 /* IDNA2008 with locale encoded inputs. */
0213
0214   extern _IDN2_API int
0215     idn2_lookup_ul (const char *src, char **lookupname, int flags);
0216
0217   extern _IDN2_API int
0218     idn2_register_ul (const char *ulabel, const char *alabel,
0219               char **insertname, int flags);
0220
0221 /**
0222  * idn2_rc:
0223  * @IDN2_OK: Successful return.
0224  * @IDN2_MALLOC: Memory allocation error.
0225  * @IDN2_NO_CODESET: Could not determine locale string encoding format.
0226  * @IDN2_ICONV_FAIL: Could not transcode locale string to UTF-8.
0227  * @IDN2_ENCODING_ERROR: Unicode data encoding error.
0228  * @IDN2_NFC: Error normalizing string.
0229  * @IDN2_PUNYCODE_BAD_INPUT: Punycode invalid input.
0230  * @IDN2_PUNYCODE_BIG_OUTPUT: Punycode output buffer too small.
0231  * @IDN2_PUNYCODE_OVERFLOW: Punycode conversion would overflow.
0232  * @IDN2_TOO_BIG_DOMAIN: Domain name longer than 255 characters.
0233  * @IDN2_TOO_BIG_LABEL: Domain label longer than 63 characters.
0234  * @IDN2_INVALID_ALABEL: Input A-label is not valid.
0235  * @IDN2_UALABEL_MISMATCH: Input A-label and U-label does not match.
0236  * @IDN2_INVALID_FLAGS: Invalid combination of flags.
0237  * @IDN2_NOT_NFC: String is not NFC.
0238  * @IDN2_2HYPHEN: String has forbidden two hyphens.
0239  * @IDN2_HYPHEN_STARTEND: String has forbidden starting/ending hyphen.
0240  * @IDN2_LEADING_COMBINING: String has forbidden leading combining character.
0241  * @IDN2_DISALLOWED: String has disallowed character.
0242  * @IDN2_CONTEXTJ: String has forbidden context-j character.
0243  * @IDN2_CONTEXTJ_NO_RULE: String has context-j character with no rull.
0244  * @IDN2_CONTEXTO: String has forbidden context-o character.
0245  * @IDN2_CONTEXTO_NO_RULE: String has context-o character with no rull.
0246  * @IDN2_UNASSIGNED: String has forbidden unassigned character.
0247  * @IDN2_BIDI: String has forbidden bi-directional properties.
0248  * @IDN2_DOT_IN_LABEL: Label has forbidden dot (TR46).
0249  * @IDN2_INVALID_TRANSITIONAL: Label has character forbidden in transitional mode (TR46).
0250  * @IDN2_INVALID_NONTRANSITIONAL: Label has character forbidden in non-transitional mode (TR46).
0251  * @IDN2_ALABEL_ROUNDTRIP_FAILED: ALabel -> Ulabel -> ALabel result differs from input.
0252  *
0253  * Return codes for IDN2 functions.  All return codes are negative
0254  * except for the successful code IDN2_OK which are guaranteed to be
0255  * 0.  Positive values are reserved for non-error return codes.
0256  *
0257  * Note that the #idn2_rc enumeration may be extended at a later date
0258  * to include new return codes.
0259  */
0260   typedef enum
0261   {
0262     IDN2_OK = 0,
0263     IDN2_MALLOC = -100,
0264     IDN2_NO_CODESET = -101,
0265     IDN2_ICONV_FAIL = -102,
0266     IDN2_ENCODING_ERROR = -200,
0267     IDN2_NFC = -201,
0268     IDN2_PUNYCODE_BAD_INPUT = -202,
0269     IDN2_PUNYCODE_BIG_OUTPUT = -203,
0270     IDN2_PUNYCODE_OVERFLOW = -204,
0271     IDN2_TOO_BIG_DOMAIN = -205,
0272     IDN2_TOO_BIG_LABEL = -206,
0273     IDN2_INVALID_ALABEL = -207,
0274     IDN2_UALABEL_MISMATCH = -208,
0275     IDN2_INVALID_FLAGS = -209,
0276     IDN2_NOT_NFC = -300,
0277     IDN2_2HYPHEN = -301,
0278     IDN2_HYPHEN_STARTEND = -302,
0279     IDN2_LEADING_COMBINING = -303,
0280     IDN2_DISALLOWED = -304,
0281     IDN2_CONTEXTJ = -305,
0282     IDN2_CONTEXTJ_NO_RULE = -306,
0283     IDN2_CONTEXTO = -307,
0284     IDN2_CONTEXTO_NO_RULE = -308,
0285     IDN2_UNASSIGNED = -309,
0286     IDN2_BIDI = -310,
0287     IDN2_DOT_IN_LABEL = -311,
0288     IDN2_INVALID_TRANSITIONAL = -312,
0289     IDN2_INVALID_NONTRANSITIONAL = -313,
0290     IDN2_ALABEL_ROUNDTRIP_FAILED = -314,
0291   } idn2_rc;
0292
0293 /* Auxiliary functions. */
0294
0295   extern _IDN2_API int idn2_to_ascii_4i (const uint32_t * input, size_t inlen,
0296                      char *output, int flags);
0297   extern _IDN2_API int idn2_to_ascii_4i2 (const uint32_t * input,
0298                       size_t inlen, char **output,
0299                       int flags);
0300   extern _IDN2_API int idn2_to_ascii_4z (const uint32_t * input,
0301                      char **output, int flags);
0302   extern _IDN2_API int idn2_to_ascii_8z (const char *input, char **output,
0303                      int flags);
0304   extern _IDN2_API int idn2_to_ascii_lz (const char *input, char **output,
0305                      int flags);
0306
0307   extern _IDN2_API int idn2_to_unicode_8z4z (const char *input,
0308                          uint32_t ** output,
0309                          int flags G_GNUC_UNUSED);
0310   extern _IDN2_API int idn2_to_unicode_4z4z (const uint32_t * input,
0311                          uint32_t ** output, int flags);
0312   extern _IDN2_API int idn2_to_unicode_44i (const uint32_t * in, size_t inlen,
0313                         uint32_t * out, size_t *outlen,
0314                         int flags);
0315   extern _IDN2_API int idn2_to_unicode_8z8z (const char *input, char **output,
0316                          int flags);
0317   extern _IDN2_API int idn2_to_unicode_8zlz (const char *input, char **output,
0318                          int flags);
0319   extern _IDN2_API int idn2_to_unicode_lzlz (const char *input, char **output,
0320                          int flags);
0321
0322   extern _IDN2_API int idn2_punycode_encode (const uint32_t * input,
0323                          size_t input_length,
0324                          char *output,
0325                          size_t *output_length);
0326   extern _IDN2_API int idn2_punycode_decode (const char *input,
0327                          size_t input_length,
0328                          uint32_t * output,
0329                          size_t *output_length);
0330
0331   extern _IDN2_API const char *idn2_strerror (int rc)
0332     G_GNUC_IDN2_ATTRIBUTE_CONST;
0333   extern _IDN2_API const char *idn2_strerror_name (int rc)
0334     G_GNUC_IDN2_ATTRIBUTE_CONST;
0335
0336   extern _IDN2_API const char *idn2_check_version (const char *req_version)
0337     G_GNUC_IDN2_ATTRIBUTE_PURE;
0338
0339   extern _IDN2_API void idn2_free (void *ptr);
0340
0341 # ifndef __GTK_DOC_IGNORE__
0342 /*** libidn compatibility layer ***/
0343 #  if !defined IDNA_H && !defined IDN2_SKIP_LIBIDN_COMPAT
0344
0345 /**
0346  * Idna_rc:
0347  * @IDNA_SUCCESS: Same as %IDN2_OK
0348  * @IDNA_STRINGPREP_ERROR: Same as %IDN2_ENCODING_ERROR
0349  * @IDNA_PUNYCODE_ERROR: Same as %IDN2_PUNYCODE_BAD_INPUT
0350  * @IDNA_CONTAINS_NON_LDH: Same as %IDN2_ENCODING_ERROR
0351  * @IDNA_CONTAINS_LDH: Same as %IDNA_CONTAINS_NON_LDH
0352  * @IDNA_CONTAINS_MINUS: Same as %IDN2_ENCODING_ERROR
0353  * @IDNA_INVALID_LENGTH: Same as %IDN2_DISALLOWED
0354  * @IDNA_NO_ACE_PREFIX: Same as %IDN2_ENCODING_ERROR
0355  * @IDNA_ROUNDTRIP_VERIFY_ERROR: Same as %IDN2_ENCODING_ERROR
0356  * @IDNA_CONTAINS_ACE_PREFIX: Same as %IDN2_ENCODING_ERROR
0357  * @IDNA_ICONV_ERROR: Same as %IDN2_ENCODING_ERROR
0358  * @IDNA_MALLOC_ERROR: Same as %IDN2_MALLOC
0359  * @IDNA_DLOPEN_ERROR: Same as %IDN2_MALLOC
0360  *
0361  * Return codes for transition to / compatibility with libidn2.
0362  *
0363  * Please be aware that return codes from idna_ functions might be unexpected
0364  * when linked / built with libidn2.
0365  */
0366   typedef enum
0367   {
0368     IDNA_SUCCESS = IDN2_OK,
0369     IDNA_STRINGPREP_ERROR = IDN2_ENCODING_ERROR,
0370     IDNA_PUNYCODE_ERROR = IDN2_PUNYCODE_BAD_INPUT,
0371     IDNA_CONTAINS_NON_LDH = IDN2_ENCODING_ERROR,
0372     IDNA_CONTAINS_LDH = IDNA_CONTAINS_NON_LDH,
0373     IDNA_CONTAINS_MINUS = IDN2_ENCODING_ERROR,
0374     IDNA_INVALID_LENGTH = IDN2_DISALLOWED,
0375     IDNA_NO_ACE_PREFIX = IDN2_ENCODING_ERROR,
0376     IDNA_ROUNDTRIP_VERIFY_ERROR = IDN2_ENCODING_ERROR,
0377     IDNA_CONTAINS_ACE_PREFIX = IDN2_ENCODING_ERROR,
0378     IDNA_ICONV_ERROR = IDN2_ENCODING_ERROR,
0379     IDNA_MALLOC_ERROR = IDN2_MALLOC,
0380     IDNA_DLOPEN_ERROR = IDN2_MALLOC
0381   } Idna_rc;
0382
0383 /**
0384  * Idna_flags:
0385  * @IDNA_ALLOW_UNASSIGNED: Same as %IDN2_ALLOW_UNASSIGNED
0386  * @IDNA_USE_STD3_ASCII_RULES: Same as %IDN2_USE_STD3_ASCII_RULES
0387  *
0388  * Flags for transition to / compatibility with libidn2.
0389  */
0390   typedef enum
0391   {
0392     IDNA_ALLOW_UNASSIGNED = IDN2_ALLOW_UNASSIGNED,
0393     IDNA_USE_STD3_ASCII_RULES = IDN2_USE_STD3_ASCII_RULES
0394   } Idna_flags;
0395
0396 #   define idna_to_ascii_4i(i,l,o,f)  idn2_to_ascii_4i(i,l,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0397 #   define idna_to_ascii_4z(i,o,f)  idn2_to_ascii_4z(i,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0398 #   define idna_to_ascii_8z(i,o,f)  idn2_to_ascii_8z(i,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0399 #   define idna_to_ascii_lz(i,o,f)  idn2_to_ascii_lz(i,o,f|IDN2_NFC_INPUT|IDN2_NONTRANSITIONAL)
0400
0401 #   define idna_to_unicode_8z4z  idn2_to_unicode_8z4z
0402 #   define idna_to_unicode_4z4z  idn2_to_unicode_4z4z
0403 #   define idna_to_unicode_44i   idn2_to_unicode_44i
0404 #   define idna_to_unicode_8z8z  idn2_to_unicode_8z8z
0405 #   define idna_to_unicode_8zlz  idn2_to_unicode_8zlz
0406 #   define idna_to_unicode_lzlz  idn2_to_unicode_lzlz
0407
0408 #   define idna_strerror         idn2_strerror
0409 #   define idn_free              idn2_free
0410
0411 #  endif            /* IDNA_H */
0412 # endif
0413
0414 # ifdef __cplusplus
0415 }
0416 # endif
0417
0418 #endif              /* IDN2_H */