icuSources/common/unicode/uidna.h

   1 /*
   2  *******************************************************************************
   3  *
   4  *   Copyright (C) 2003-2006, International Business Machines
   5  *   Corporation and others.  All Rights Reserved.
   6  *
   7  *******************************************************************************
   8  *   file name:  uidna.h
   9  *   encoding:   US-ASCII
  10  *   tab size:   8 (not used)
  11  *   indentation:4
  12  *
  13  *   created on: 2003feb1
  14  *   created by: Ram Viswanadha
  15  */
  16
  17 #ifndef __UIDNA_H__
  18 #define __UIDNA_H__
  19
  20 #include "unicode/utypes.h"
  21
  22 #if !UCONFIG_NO_IDNA
  23
  24 #include "unicode/parseerr.h"
  25
  26 /**
  27  * \file
  28  * \brief C API: Internationalized Domain Names in Applications Tranformation
  29  *
  30  * UIDNA API implements the IDNA protocol as defined in the IDNA RFC
  31  * (http://www.ietf.org/rfc/rfc3490.txt).
  32  * The RFC defines 2 operations: ToASCII and ToUnicode. Domain labels
  33  * containing non-ASCII code points are required to be processed by
  34  * ToASCII operation before passing it to resolver libraries. Domain names
  35  * that are obtained from resolver libraries are required to be processed by
  36  * ToUnicode operation before displaying the domain name to the user.
  37  * IDNA requires that implementations process input strings with Nameprep
  38  * (http://www.ietf.org/rfc/rfc3491.txt),
  39  * which is a profile of Stringprep (http://www.ietf.org/rfc/rfc3454.txt),
  40  * and then with Punycode (http://www.ietf.org/rfc/rfc3492.txt).
  41  * Implementations of IDNA MUST fully implement Nameprep and Punycode;
  42  * neither Nameprep nor Punycode are optional.
  43  * The input and output of ToASCII and ToUnicode operations are Unicode
  44  * and are designed to be chainable, i.e., applying ToASCII or ToUnicode operations
  45  * multiple times to an input string will yield the same result as applying the operation
  46  * once.
  47  * ToUnicode(ToUnicode(ToUnicode...(ToUnicode(string)))) == ToUnicode(string)
  48  * ToASCII(ToASCII(ToASCII...(ToASCII(string))) == ToASCII(string).
  49  *
  50  */
  51
  52 /**
  53  * Option to prohibit processing of unassigned codepoints in the input and
  54  * do not check if the input conforms to STD-3 ASCII rules.
  55  *
  56  * @see  uidna_toASCII uidna_toUnicode
  57  * @stable ICU 2.6
  58  */
  59 #define UIDNA_DEFAULT          0x0000
  60 /**
  61  * Option to allow processing of unassigned codepoints in the input
  62  *
  63  * @see  uidna_toASCII uidna_toUnicode
  64  * @stable ICU 2.6
  65  */
  66 #define UIDNA_ALLOW_UNASSIGNED 0x0001
  67 /**
  68  * Option to check if input conforms to STD-3 ASCII rules
  69  *
  70  * @see  uidna_toASCII uidna_toUnicode
  71  * @stable ICU 2.6
  72  */
  73 #define UIDNA_USE_STD3_RULES   0x0002
  74
  75 /**
  76  * This function implements the ToASCII operation as defined in the IDNA RFC.
  77  * This operation is done on <b>single labels</b> before sending it to something that expects
  78  * ASCII names. A label is an individual part of a domain name. Labels are usually
  79  * separated by dots; e.g." "www.example.com" is composed of 3 labels
  80  * "www","example", and "com".
  81  *
  82  *
  83  * @param src               Input UChar array containing label in Unicode.
  84  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
  85  * @param dest              Output UChar array with ASCII (ACE encoded) label.
  86  * @param destCapacity      Size of dest.
  87  * @param options           A bit set of options:
  88  *
  89  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
  90  *                              and do not use STD3 ASCII rules
  91  *                              If unassigned code points are found the operation fails with
  92  *                              U_UNASSIGNED_ERROR error code.
  93  *
  94  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
  95  *                              If this option is set, the unassigned code points are in the input
  96  *                              are treated as normal Unicode code points.
  97  *
  98  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
  99  *                              If this option is set and the input does not satisfy STD3 rules,
 100  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 101  *
 102  * @param parseError        Pointer to UParseError struct to receive information on position
 103  *                          of error if an error is encountered. Can be NULL.
 104  * @param status            ICU in/out error code parameter.
 105  *                          U_INVALID_CHAR_FOUND if src contains
 106  *                          unmatched single surrogates.
 107  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 108  *                          too many code points.
 109  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 110  * @return                  Number of ASCII characters converted.
 111  * @stable ICU 2.6
 112  */
 113 U_STABLE int32_t U_EXPORT2
 114 uidna_toASCII(const UChar* src, int32_t srcLength,
 115               UChar* dest, int32_t destCapacity,
 116               int32_t options,
 117               UParseError* parseError,
 118               UErrorCode* status);
 119
 120
 121 /**
 122  * This function implements the ToUnicode operation as defined in the IDNA RFC.
 123  * This operation is done on <b>single labels</b> before sending it to something that expects
 124  * Unicode names. A label is an individual part of a domain name. Labels are usually
 125  * separated by dots; for e.g." "www.example.com" is composed of 3 labels
 126  * "www","example", and "com".
 127  *
 128  * @param src               Input UChar array containing ASCII (ACE encoded) label.
 129  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 130  * @param dest Output       Converted UChar array containing Unicode equivalent of label.
 131  * @param destCapacity      Size of dest.
 132  * @param options           A bit set of options:
 133  *
 134  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 135  *                              and do not use STD3 ASCII rules
 136  *                              If unassigned code points are found the operation fails with
 137  *                              U_UNASSIGNED_ERROR error code.
 138  *
 139  *  - UIDNA_ALLOW_UNASSIGNED      Unassigned values can be converted to ASCII for query operations
 140  *                              If this option is set, the unassigned code points are in the input
 141  *                              are treated as normal Unicode code points. <b> Note: </b> This option is
 142  *                              required on toUnicode operation because the RFC mandates
 143  *                              verification of decoded ACE input by applying toASCII and comparing
 144  *                              its output with source
 145  *
 146  *
 147  *
 148  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 149  *                              If this option is set and the input does not satisfy STD3 rules,
 150  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 151  *
 152  * @param parseError        Pointer to UParseError struct to receive information on position
 153  *                          of error if an error is encountered. Can be NULL.
 154  * @param status            ICU in/out error code parameter.
 155  *                          U_INVALID_CHAR_FOUND if src contains
 156  *                          unmatched single surrogates.
 157  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 158  *                          too many code points.
 159  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 160  * @return                  Number of Unicode characters converted.
 161  * @stable ICU 2.6
 162  */
 163 U_STABLE int32_t U_EXPORT2
 164 uidna_toUnicode(const UChar* src, int32_t srcLength,
 165                 UChar* dest, int32_t destCapacity,
 166                 int32_t options,
 167                 UParseError* parseError,
 168                 UErrorCode* status);
 169
 170
 171 /**
 172  * Convenience function that implements the IDNToASCII operation as defined in the IDNA RFC.
 173  * This operation is done on complete domain names, e.g: "www.example.com".
 174  * It is important to note that this operation can fail. If it fails, then the input
 175  * domain name cannot be used as an Internationalized Domain Name and the application
 176  * should have methods defined to deal with the failure.
 177  *
 178  * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name
 179  * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each,
 180  * and then convert. This function does not offer that level of granularity. The options once
 181  * set will apply to all labels in the domain name
 182  *
 183  * @param src               Input UChar array containing IDN in Unicode.
 184  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 185  * @param dest              Output UChar array with ASCII (ACE encoded) IDN.
 186  * @param destCapacity      Size of dest.
 187  * @param options           A bit set of options:
 188  *
 189  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 190  *                              and do not use STD3 ASCII rules
 191  *                              If unassigned code points are found the operation fails with
 192  *                              U_UNASSIGNED_CODE_POINT_FOUND error code.
 193  *
 194  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
 195  *                              If this option is set, the unassigned code points are in the input
 196  *                              are treated as normal Unicode code points.
 197  *
 198  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 199  *                              If this option is set and the input does not satisfy STD3 rules,
 200  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 201  *
 202  * @param parseError        Pointer to UParseError struct to receive information on position
 203  *                          of error if an error is encountered. Can be NULL.
 204  * @param status            ICU in/out error code parameter.
 205  *                          U_INVALID_CHAR_FOUND if src contains
 206  *                          unmatched single surrogates.
 207  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 208  *                          too many code points.
 209  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 210  * @return                  Number of ASCII characters converted.
 211  * @stable ICU 2.6
 212  */
 213 U_STABLE int32_t U_EXPORT2
 214 uidna_IDNToASCII(  const UChar* src, int32_t srcLength,
 215                    UChar* dest, int32_t destCapacity,
 216                    int32_t options,
 217                    UParseError* parseError,
 218                    UErrorCode* status);
 219
 220 /**
 221  * Convenience function that implements the IDNToUnicode operation as defined in the IDNA RFC.
 222  * This operation is done on complete domain names, e.g: "www.example.com".
 223  *
 224  * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name
 225  * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each,
 226  * and then convert. This function does not offer that level of granularity. The options once
 227  * set will apply to all labels in the domain name
 228  *
 229  * @param src               Input UChar array containing IDN in ASCII (ACE encoded) form.
 230  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 231  * @param dest Output       UChar array containing Unicode equivalent of source IDN.
 232  * @param destCapacity      Size of dest.
 233  * @param options           A bit set of options:
 234  *
 235  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 236  *                              and do not use STD3 ASCII rules
 237  *                              If unassigned code points are found the operation fails with
 238  *                              U_UNASSIGNED_CODE_POINT_FOUND error code.
 239  *
 240  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
 241  *                              If this option is set, the unassigned code points are in the input
 242  *                              are treated as normal Unicode code points.
 243  *
 244  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 245  *                              If this option is set and the input does not satisfy STD3 rules,
 246  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 247  *
 248  * @param parseError        Pointer to UParseError struct to receive information on position
 249  *                          of error if an error is encountered. Can be NULL.
 250  * @param status            ICU in/out error code parameter.
 251  *                          U_INVALID_CHAR_FOUND if src contains
 252  *                          unmatched single surrogates.
 253  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 254  *                          too many code points.
 255  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 256  * @return                  Number of ASCII characters converted.
 257  * @stable ICU 2.6
 258  */
 259 U_STABLE int32_t U_EXPORT2
 260 uidna_IDNToUnicode(  const UChar* src, int32_t srcLength,
 261                      UChar* dest, int32_t destCapacity,
 262                      int32_t options,
 263                      UParseError* parseError,
 264                      UErrorCode* status);
 265
 266 /**
 267  * Compare two IDN strings for equivalence.
 268  * This function splits the domain names into labels and compares them.
 269  * According to IDN RFC, whenever two labels are compared, they are
 270  * considered equal if and only if their ASCII forms (obtained by
 271  * applying toASCII) match using an case-insensitive ASCII comparison.
 272  * Two domain names are considered a match if and only if all labels
 273  * match regardless of whether label separators match.
 274  *
 275  * @param s1                First source string.
 276  * @param length1           Length of first source string, or -1 if NUL-terminated.
 277  *
 278  * @param s2                Second source string.
 279  * @param length2           Length of second source string, or -1 if NUL-terminated.
 280  * @param options           A bit set of options:
 281  *
 282  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 283  *                              and do not use STD3 ASCII rules
 284  *                              If unassigned code points are found the operation fails with
 285  *                              U_UNASSIGNED_CODE_POINT_FOUND error code.
 286  *
 287  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
 288  *                              If this option is set, the unassigned code points are in the input
 289  *                              are treated as normal Unicode code points.
 290  *
 291  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 292  *                              If this option is set and the input does not satisfy STD3 rules,
 293  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 294  *
 295  * @param status            ICU error code in/out parameter.
 296  *                          Must fulfill U_SUCCESS before the function call.
 297  * @return <0 or 0 or >0 as usual for string comparisons
 298  * @stable ICU 2.6
 299  */
 300 U_STABLE int32_t U_EXPORT2
 301 uidna_compare(  const UChar *s1, int32_t length1,
 302                 const UChar *s2, int32_t length2,
 303                 int32_t options,
 304                 UErrorCode* status);
 305
 306 #endif /* #if !UCONFIG_NO_IDNA */
 307
 308 #endif