icuSources/common/unicode/uidna.h

   1 /*
   2  *******************************************************************************
   3  *
   4  *   Copyright (C) 2003-2012, 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/localpointer.h"
  25 #include "unicode/parseerr.h"
  26
  27 /**
  28  * \file
  29  * \brief C API: Internationalizing Domain Names in Applications (IDNA)
  30  *
  31  * IDNA2008 is implemented according to UTS #46, see the IDNA C++ class in idna.h.
  32  *
  33  * The C API functions which do take a UIDNA * service object pointer
  34  * implement UTS #46 and IDNA2008.
  35  * The C API functions which do not take a service object pointer
  36  * implement IDNA2003.
  37  */
  38
  39 /*
  40  * IDNA option bit set values.
  41  */
  42 enum {
  43     /**
  44      * Default options value: None of the other options are set.
  45      * For use in static worker and factory methods.
  46      * @stable ICU 2.6
  47      */
  48     UIDNA_DEFAULT=0,
  49     /**
  50      * Option to allow unassigned code points in domain names and labels.
  51      * For use in static worker and factory methods.
  52      * <p>This option is ignored by the UTS46 implementation.
  53      * (UTS #46 disallows unassigned code points.)
  54      * @stable ICU 2.6
  55      */
  56     UIDNA_ALLOW_UNASSIGNED=1,
  57     /**
  58      * Option to check whether the input conforms to the STD3 ASCII rules,
  59      * for example the restriction of labels to LDH characters
  60      * (ASCII Letters, Digits and Hyphen-Minus).
  61      * For use in static worker and factory methods.
  62      * @stable ICU 2.6
  63      */
  64     UIDNA_USE_STD3_RULES=2,
  65     /**
  66      * IDNA option to check for whether the input conforms to the BiDi rules.
  67      * For use in static worker and factory methods.
  68      * <p>This option is ignored by the IDNA2003 implementation.
  69      * (IDNA2003 always performs a BiDi check.)
  70      * @stable ICU 4.6
  71      */
  72     UIDNA_CHECK_BIDI=4,
  73     /**
  74      * IDNA option to check for whether the input conforms to the CONTEXTJ rules.
  75      * For use in static worker and factory methods.
  76      * <p>This option is ignored by the IDNA2003 implementation.
  77      * (The CONTEXTJ check is new in IDNA2008.)
  78      * @stable ICU 4.6
  79      */
  80     UIDNA_CHECK_CONTEXTJ=8,
  81     /**
  82      * IDNA option for nontransitional processing in ToASCII().
  83      * For use in static worker and factory methods.
  84      * <p>By default, ToASCII() uses transitional processing.
  85      * <p>This option is ignored by the IDNA2003 implementation.
  86      * (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.)
  87      * @stable ICU 4.6
  88      */
  89     UIDNA_NONTRANSITIONAL_TO_ASCII=0x10,
  90     /**
  91      * IDNA option for nontransitional processing in ToUnicode().
  92      * For use in static worker and factory methods.
  93      * <p>By default, ToUnicode() uses transitional processing.
  94      * <p>This option is ignored by the IDNA2003 implementation.
  95      * (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.)
  96      * @stable ICU 4.6
  97      */
  98     UIDNA_NONTRANSITIONAL_TO_UNICODE=0x20,
  99 #ifndef U_HIDE_DRAFT_API
 100     /**
 101      * IDNA option to check for whether the input conforms to the CONTEXTO rules.
 102      * For use in static worker and factory methods.
 103      * <p>This option is ignored by the IDNA2003 implementation.
 104      * (The CONTEXTO check is new in IDNA2008.)
 105      * <p>This is for use by registries for IDNA2008 conformance.
 106      * UTS #46 does not require the CONTEXTO check.
 107      * @draft ICU 49
 108      */
 109     UIDNA_CHECK_CONTEXTO=0x40
 110 #endif  /* U_HIDE_DRAFT_API */
 111 };
 112
 113 /**
 114  * Opaque C service object type for the new IDNA API.
 115  * @stable ICU 4.6
 116  */
 117 struct UIDNA;
 118 typedef struct UIDNA UIDNA;  /**< C typedef for struct UIDNA. @stable ICU 4.6 */
 119
 120 /**
 121  * Returns a UIDNA instance which implements UTS #46.
 122  * Returns an unmodifiable instance, owned by the caller.
 123  * Cache it for multiple operations, and uidna_close() it when done.
 124  * The instance is thread-safe, that is, it can be used concurrently.
 125  *
 126  * For details about the UTS #46 implementation see the IDNA C++ class in idna.h.
 127  *
 128  * @param options Bit set to modify the processing and error checking.
 129  *                See option bit set values in uidna.h.
 130  * @param pErrorCode Standard ICU error code. Its input value must
 131  *                  pass the U_SUCCESS() test, or else the function returns
 132  *                  immediately. Check for U_FAILURE() on output or use with
 133  *                  function chaining. (See User Guide for details.)
 134  * @return the UTS #46 UIDNA instance, if successful
 135  * @stable ICU 4.6
 136  */
 137 U_DRAFT UIDNA * U_EXPORT2
 138 uidna_openUTS46(uint32_t options, UErrorCode *pErrorCode);
 139
 140 /**
 141  * Closes a UIDNA instance.
 142  * @param idna UIDNA instance to be closed
 143  * @stable ICU 4.6
 144  */
 145 U_DRAFT void U_EXPORT2
 146 uidna_close(UIDNA *idna);
 147
 148 #if U_SHOW_CPLUSPLUS_API
 149
 150 U_NAMESPACE_BEGIN
 151
 152 /**
 153  * \class LocalUIDNAPointer
 154  * "Smart pointer" class, closes a UIDNA via uidna_close().
 155  * For most methods see the LocalPointerBase base class.
 156  *
 157  * @see LocalPointerBase
 158  * @see LocalPointer
 159  * @stable ICU 4.6
 160  */
 161 U_DEFINE_LOCAL_OPEN_POINTER(LocalUIDNAPointer, UIDNA, uidna_close);
 162
 163 U_NAMESPACE_END
 164
 165 #endif
 166
 167 /**
 168  * Output container for IDNA processing errors.
 169  * Initialize with UIDNA_INFO_INITIALIZER:
 170  * \code
 171  * UIDNAInfo info = UIDNA_INFO_INITIALIZER;
 172  * int32_t length = uidna_nameToASCII(..., &info, &errorCode);
 173  * if(U_SUCCESS(errorCode) && info.errors!=0) { ... }
 174  * \endcode
 175  * @stable ICU 4.6
 176  */
 177 struct UIDNAInfo {
 178     /** sizeof(UIDNAInfo) @stable ICU 4.6 */
 179     int16_t size;
 180     /**
 181      * Set to TRUE if transitional and nontransitional processing produce different results.
 182      * For details see C++ IDNAInfo::isTransitionalDifferent().
 183      * @stable ICU 4.6
 184      */
 185     UBool isTransitionalDifferent;
 186     UBool reservedB3;  /**< Reserved field, do not use. @internal */
 187     /**
 188      * Bit set indicating IDNA processing errors. 0 if no errors.
 189      * See UIDNA_ERROR_... constants.
 190      * @stable ICU 4.6
 191      */
 192     uint32_t errors;
 193     int32_t reservedI2;  /**< Reserved field, do not use. @internal */
 194     int32_t reservedI3;  /**< Reserved field, do not use. @internal */
 195 };
 196 typedef struct UIDNAInfo UIDNAInfo;
 197
 198 /**
 199  * Static initializer for a UIDNAInfo struct.
 200  * @stable ICU 4.6
 201  */
 202 #define UIDNA_INFO_INITIALIZER { \
 203     (int16_t)sizeof(UIDNAInfo), \
 204     FALSE, FALSE, \
 205     0, 0, 0 }
 206
 207 /**
 208  * Converts a single domain name label into its ASCII form for DNS lookup.
 209  * If any processing step fails, then pInfo->errors will be non-zero and
 210  * the result might not be an ASCII string.
 211  * The label might be modified according to the types of errors.
 212  * Labels with severe errors will be left in (or turned into) their Unicode form.
 213  *
 214  * The UErrorCode indicates an error only in exceptional cases,
 215  * such as a U_MEMORY_ALLOCATION_ERROR.
 216  *
 217  * @param idna UIDNA instance
 218  * @param label Input domain name label
 219  * @param length Label length, or -1 if NUL-terminated
 220  * @param dest Destination string buffer
 221  * @param capacity Destination buffer capacity
 222  * @param pInfo Output container of IDNA processing details.
 223  * @param pErrorCode Standard ICU error code. Its input value must
 224  *                  pass the U_SUCCESS() test, or else the function returns
 225  *                  immediately. Check for U_FAILURE() on output or use with
 226  *                  function chaining. (See User Guide for details.)
 227  * @return destination string length
 228  * @stable ICU 4.6
 229  */
 230 U_DRAFT int32_t U_EXPORT2
 231 uidna_labelToASCII(const UIDNA *idna,
 232                    const UChar *label, int32_t length,
 233                    UChar *dest, int32_t capacity,
 234                    UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 235
 236 /**
 237  * Converts a single domain name label into its Unicode form for human-readable display.
 238  * If any processing step fails, then pInfo->errors will be non-zero.
 239  * The label might be modified according to the types of errors.
 240  *
 241  * The UErrorCode indicates an error only in exceptional cases,
 242  * such as a U_MEMORY_ALLOCATION_ERROR.
 243  *
 244  * @param idna UIDNA instance
 245  * @param label Input domain name label
 246  * @param length Label length, or -1 if NUL-terminated
 247  * @param dest Destination string buffer
 248  * @param capacity Destination buffer capacity
 249  * @param pInfo Output container of IDNA processing details.
 250  * @param pErrorCode Standard ICU error code. Its input value must
 251  *                  pass the U_SUCCESS() test, or else the function returns
 252  *                  immediately. Check for U_FAILURE() on output or use with
 253  *                  function chaining. (See User Guide for details.)
 254  * @return destination string length
 255  * @stable ICU 4.6
 256  */
 257 U_DRAFT int32_t U_EXPORT2
 258 uidna_labelToUnicode(const UIDNA *idna,
 259                      const UChar *label, int32_t length,
 260                      UChar *dest, int32_t capacity,
 261                      UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 262
 263 /**
 264  * Converts a whole domain name into its ASCII form for DNS lookup.
 265  * If any processing step fails, then pInfo->errors will be non-zero and
 266  * the result might not be an ASCII string.
 267  * The domain name might be modified according to the types of errors.
 268  * Labels with severe errors will be left in (or turned into) their Unicode form.
 269  *
 270  * The UErrorCode indicates an error only in exceptional cases,
 271  * such as a U_MEMORY_ALLOCATION_ERROR.
 272  *
 273  * @param idna UIDNA instance
 274  * @param name Input domain name
 275  * @param length Domain name length, or -1 if NUL-terminated
 276  * @param dest Destination string buffer
 277  * @param capacity Destination buffer capacity
 278  * @param pInfo Output container of IDNA processing details.
 279  * @param pErrorCode Standard ICU error code. Its input value must
 280  *                  pass the U_SUCCESS() test, or else the function returns
 281  *                  immediately. Check for U_FAILURE() on output or use with
 282  *                  function chaining. (See User Guide for details.)
 283  * @return destination string length
 284  * @stable ICU 4.6
 285  */
 286 U_DRAFT int32_t U_EXPORT2
 287 uidna_nameToASCII(const UIDNA *idna,
 288                   const UChar *name, int32_t length,
 289                   UChar *dest, int32_t capacity,
 290                   UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 291
 292 /**
 293  * Converts a whole domain name into its Unicode form for human-readable display.
 294  * If any processing step fails, then pInfo->errors will be non-zero.
 295  * The domain name might be modified according to the types of errors.
 296  *
 297  * The UErrorCode indicates an error only in exceptional cases,
 298  * such as a U_MEMORY_ALLOCATION_ERROR.
 299  *
 300  * @param idna UIDNA instance
 301  * @param name Input domain name
 302  * @param length Domain name length, or -1 if NUL-terminated
 303  * @param dest Destination string buffer
 304  * @param capacity Destination buffer capacity
 305  * @param pInfo Output container of IDNA processing details.
 306  * @param pErrorCode Standard ICU error code. Its input value must
 307  *                  pass the U_SUCCESS() test, or else the function returns
 308  *                  immediately. Check for U_FAILURE() on output or use with
 309  *                  function chaining. (See User Guide for details.)
 310  * @return destination string length
 311  * @stable ICU 4.6
 312  */
 313 U_DRAFT int32_t U_EXPORT2
 314 uidna_nameToUnicode(const UIDNA *idna,
 315                     const UChar *name, int32_t length,
 316                     UChar *dest, int32_t capacity,
 317                     UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 318
 319 /* UTF-8 versions of the processing methods --------------------------------- */
 320
 321 /**
 322  * Converts a single domain name label into its ASCII form for DNS lookup.
 323  * UTF-8 version of uidna_labelToASCII(), same behavior.
 324  *
 325  * @param idna UIDNA instance
 326  * @param label Input domain name label
 327  * @param length Label length, or -1 if NUL-terminated
 328  * @param dest Destination string buffer
 329  * @param capacity Destination buffer capacity
 330  * @param pInfo Output container of IDNA processing details.
 331  * @param pErrorCode Standard ICU error code. Its input value must
 332  *                  pass the U_SUCCESS() test, or else the function returns
 333  *                  immediately. Check for U_FAILURE() on output or use with
 334  *                  function chaining. (See User Guide for details.)
 335  * @return destination string length
 336  * @stable ICU 4.6
 337  */
 338 U_DRAFT int32_t U_EXPORT2
 339 uidna_labelToASCII_UTF8(const UIDNA *idna,
 340                         const char *label, int32_t length,
 341                         char *dest, int32_t capacity,
 342                         UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 343
 344 /**
 345  * Converts a single domain name label into its Unicode form for human-readable display.
 346  * UTF-8 version of uidna_labelToUnicode(), same behavior.
 347  *
 348  * @param idna UIDNA instance
 349  * @param label Input domain name label
 350  * @param length Label length, or -1 if NUL-terminated
 351  * @param dest Destination string buffer
 352  * @param capacity Destination buffer capacity
 353  * @param pInfo Output container of IDNA processing details.
 354  * @param pErrorCode Standard ICU error code. Its input value must
 355  *                  pass the U_SUCCESS() test, or else the function returns
 356  *                  immediately. Check for U_FAILURE() on output or use with
 357  *                  function chaining. (See User Guide for details.)
 358  * @return destination string length
 359  * @stable ICU 4.6
 360  */
 361 U_DRAFT int32_t U_EXPORT2
 362 uidna_labelToUnicodeUTF8(const UIDNA *idna,
 363                          const char *label, int32_t length,
 364                          char *dest, int32_t capacity,
 365                          UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 366
 367 /**
 368  * Converts a whole domain name into its ASCII form for DNS lookup.
 369  * UTF-8 version of uidna_nameToASCII(), same behavior.
 370  *
 371  * @param idna UIDNA instance
 372  * @param name Input domain name
 373  * @param length Domain name length, or -1 if NUL-terminated
 374  * @param dest Destination string buffer
 375  * @param capacity Destination buffer capacity
 376  * @param pInfo Output container of IDNA processing details.
 377  * @param pErrorCode Standard ICU error code. Its input value must
 378  *                  pass the U_SUCCESS() test, or else the function returns
 379  *                  immediately. Check for U_FAILURE() on output or use with
 380  *                  function chaining. (See User Guide for details.)
 381  * @return destination string length
 382  * @stable ICU 4.6
 383  */
 384 U_DRAFT int32_t U_EXPORT2
 385 uidna_nameToASCII_UTF8(const UIDNA *idna,
 386                        const char *name, int32_t length,
 387                        char *dest, int32_t capacity,
 388                        UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 389
 390 /**
 391  * Converts a whole domain name into its Unicode form for human-readable display.
 392  * UTF-8 version of uidna_nameToUnicode(), same behavior.
 393  *
 394  * @param idna UIDNA instance
 395  * @param name Input domain name
 396  * @param length Domain name length, or -1 if NUL-terminated
 397  * @param dest Destination string buffer
 398  * @param capacity Destination buffer capacity
 399  * @param pInfo Output container of IDNA processing details.
 400  * @param pErrorCode Standard ICU error code. Its input value must
 401  *                  pass the U_SUCCESS() test, or else the function returns
 402  *                  immediately. Check for U_FAILURE() on output or use with
 403  *                  function chaining. (See User Guide for details.)
 404  * @return destination string length
 405  * @stable ICU 4.6
 406  */
 407 U_DRAFT int32_t U_EXPORT2
 408 uidna_nameToUnicodeUTF8(const UIDNA *idna,
 409                         const char *name, int32_t length,
 410                         char *dest, int32_t capacity,
 411                         UIDNAInfo *pInfo, UErrorCode *pErrorCode);
 412
 413 /*
 414  * IDNA error bit set values.
 415  * When a domain name or label fails a processing step or does not meet the
 416  * validity criteria, then one or more of these error bits are set.
 417  */
 418 enum {
 419     /**
 420      * A non-final domain name label (or the whole domain name) is empty.
 421      * @stable ICU 4.6
 422      */
 423     UIDNA_ERROR_EMPTY_LABEL=1,
 424     /**
 425      * A domain name label is longer than 63 bytes.
 426      * (See STD13/RFC1034 3.1. Name space specifications and terminology.)
 427      * This is only checked in ToASCII operations, and only if the output label is all-ASCII.
 428      * @stable ICU 4.6
 429      */
 430     UIDNA_ERROR_LABEL_TOO_LONG=2,
 431     /**
 432      * A domain name is longer than 255 bytes in its storage form.
 433      * (See STD13/RFC1034 3.1. Name space specifications and terminology.)
 434      * This is only checked in ToASCII operations, and only if the output domain name is all-ASCII.
 435      * @stable ICU 4.6
 436      */
 437     UIDNA_ERROR_DOMAIN_NAME_TOO_LONG=4,
 438     /**
 439      * A label starts with a hyphen-minus ('-').
 440      * @stable ICU 4.6
 441      */
 442     UIDNA_ERROR_LEADING_HYPHEN=8,
 443     /**
 444      * A label ends with a hyphen-minus ('-').
 445      * @stable ICU 4.6
 446      */
 447     UIDNA_ERROR_TRAILING_HYPHEN=0x10,
 448     /**
 449      * A label contains hyphen-minus ('-') in the third and fourth positions.
 450      * @stable ICU 4.6
 451      */
 452     UIDNA_ERROR_HYPHEN_3_4=0x20,
 453     /**
 454      * A label starts with a combining mark.
 455      * @stable ICU 4.6
 456      */
 457     UIDNA_ERROR_LEADING_COMBINING_MARK=0x40,
 458     /**
 459      * A label or domain name contains disallowed characters.
 460      * @stable ICU 4.6
 461      */
 462     UIDNA_ERROR_DISALLOWED=0x80,
 463     /**
 464      * A label starts with "xn--" but does not contain valid Punycode.
 465      * That is, an xn-- label failed Punycode decoding.
 466      * @stable ICU 4.6
 467      */
 468     UIDNA_ERROR_PUNYCODE=0x100,
 469     /**
 470      * A label contains a dot=full stop.
 471      * This can occur in an input string for a single-label function.
 472      * @stable ICU 4.6
 473      */
 474     UIDNA_ERROR_LABEL_HAS_DOT=0x200,
 475     /**
 476      * An ACE label does not contain a valid label string.
 477      * The label was successfully ACE (Punycode) decoded but the resulting
 478      * string had severe validation errors. For example,
 479      * it might contain characters that are not allowed in ACE labels,
 480      * or it might not be normalized.
 481      * @stable ICU 4.6
 482      */
 483     UIDNA_ERROR_INVALID_ACE_LABEL=0x400,
 484     /**
 485      * A label does not meet the IDNA BiDi requirements (for right-to-left characters).
 486      * @stable ICU 4.6
 487      */
 488     UIDNA_ERROR_BIDI=0x800,
 489     /**
 490      * A label does not meet the IDNA CONTEXTJ requirements.
 491      * @stable ICU 4.6
 492      */
 493     UIDNA_ERROR_CONTEXTJ=0x1000,
 494 #ifndef U_HIDE_DRAFT_API
 495     /**
 496      * A label does not meet the IDNA CONTEXTO requirements for punctuation characters.
 497      * Some punctuation characters "Would otherwise have been DISALLOWED"
 498      * but are allowed in certain contexts. (RFC 5892)
 499      * @draft ICU 49
 500      */
 501     UIDNA_ERROR_CONTEXTO_PUNCTUATION=0x2000,
 502     /**
 503      * A label does not meet the IDNA CONTEXTO requirements for digits.
 504      * Arabic-Indic Digits (U+066x) must not be mixed with Extended Arabic-Indic Digits (U+06Fx).
 505      * @draft ICU 49
 506      */
 507     UIDNA_ERROR_CONTEXTO_DIGITS=0x4000
 508 #endif  /* U_HIDE_DRAFT_API */
 509 };
 510
 511 /* IDNA2003 API ------------------------------------------------------------- */
 512
 513 /**
 514  * IDNA2003: This function implements the ToASCII operation as defined in the IDNA RFC.
 515  * This operation is done on <b>single labels</b> before sending it to something that expects
 516  * ASCII names. A label is an individual part of a domain name. Labels are usually
 517  * separated by dots; e.g. "www.example.com" is composed of 3 labels "www","example", and "com".
 518  *
 519  * IDNA2003 API Overview:
 520  *
 521  * The uidna_ API implements the IDNA protocol as defined in the IDNA RFC
 522  * (http://www.ietf.org/rfc/rfc3490.txt).
 523  * The RFC defines 2 operations: ToASCII and ToUnicode. Domain name labels
 524  * containing non-ASCII code points are processed by the
 525  * ToASCII operation before passing it to resolver libraries. Domain names
 526  * that are obtained from resolver libraries are processed by the
 527  * ToUnicode operation before displaying the domain name to the user.
 528  * IDNA requires that implementations process input strings with Nameprep
 529  * (http://www.ietf.org/rfc/rfc3491.txt),
 530  * which is a profile of Stringprep (http://www.ietf.org/rfc/rfc3454.txt),
 531  * and then with Punycode (http://www.ietf.org/rfc/rfc3492.txt).
 532  * Implementations of IDNA MUST fully implement Nameprep and Punycode;
 533  * neither Nameprep nor Punycode are optional.
 534  * The input and output of ToASCII and ToUnicode operations are Unicode
 535  * and are designed to be chainable, i.e., applying ToASCII or ToUnicode operations
 536  * multiple times to an input string will yield the same result as applying the operation
 537  * once.
 538  * ToUnicode(ToUnicode(ToUnicode...(ToUnicode(string)))) == ToUnicode(string)
 539  * ToASCII(ToASCII(ToASCII...(ToASCII(string))) == ToASCII(string).
 540  *
 541  * @param src               Input UChar array containing label in Unicode.
 542  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 543  * @param dest              Output UChar array with ASCII (ACE encoded) label.
 544  * @param destCapacity      Size of dest.
 545  * @param options           A bit set of options:
 546  *
 547  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 548  *                              and do not use STD3 ASCII rules
 549  *                              If unassigned code points are found the operation fails with
 550  *                              U_UNASSIGNED_ERROR error code.
 551  *
 552  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
 553  *                              If this option is set, the unassigned code points are in the input
 554  *                              are treated as normal Unicode code points.
 555  *
 556  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 557  *                              If this option is set and the input does not satisfy STD3 rules,
 558  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 559  *
 560  * @param parseError        Pointer to UParseError struct to receive information on position
 561  *                          of error if an error is encountered. Can be NULL.
 562  * @param status            ICU in/out error code parameter.
 563  *                          U_INVALID_CHAR_FOUND if src contains
 564  *                          unmatched single surrogates.
 565  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 566  *                          too many code points.
 567  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 568  * @return The length of the result string, if successful - or in case of a buffer overflow,
 569  *         in which case it will be greater than destCapacity.
 570  * @stable ICU 2.6
 571  */
 572 U_STABLE int32_t U_EXPORT2
 573 uidna_toASCII(const UChar* src, int32_t srcLength,
 574               UChar* dest, int32_t destCapacity,
 575               int32_t options,
 576               UParseError* parseError,
 577               UErrorCode* status);
 578
 579
 580 /**
 581  * IDNA2003: This function implements the ToUnicode operation as defined in the IDNA RFC.
 582  * This operation is done on <b>single labels</b> before sending it to something that expects
 583  * Unicode names. A label is an individual part of a domain name. Labels are usually
 584  * separated by dots; for e.g. "www.example.com" is composed of 3 labels "www","example", and "com".
 585  *
 586  * @param src               Input UChar array containing ASCII (ACE encoded) label.
 587  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 588  * @param dest Output       Converted UChar array containing Unicode equivalent of label.
 589  * @param destCapacity      Size of dest.
 590  * @param options           A bit set of options:
 591  *
 592  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 593  *                              and do not use STD3 ASCII rules
 594  *                              If unassigned code points are found the operation fails with
 595  *                              U_UNASSIGNED_ERROR error code.
 596  *
 597  *  - UIDNA_ALLOW_UNASSIGNED      Unassigned values can be converted to ASCII for query operations
 598  *                              If this option is set, the unassigned code points are in the input
 599  *                              are treated as normal Unicode code points. <b> Note: </b> This option is
 600  *                              required on toUnicode operation because the RFC mandates
 601  *                              verification of decoded ACE input by applying toASCII and comparing
 602  *                              its output with source
 603  *
 604  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 605  *                              If this option is set and the input does not satisfy STD3 rules,
 606  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 607  *
 608  * @param parseError        Pointer to UParseError struct to receive information on position
 609  *                          of error if an error is encountered. Can be NULL.
 610  * @param status            ICU in/out error code parameter.
 611  *                          U_INVALID_CHAR_FOUND if src contains
 612  *                          unmatched single surrogates.
 613  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 614  *                          too many code points.
 615  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 616  * @return The length of the result string, if successful - or in case of a buffer overflow,
 617  *         in which case it will be greater than destCapacity.
 618  * @stable ICU 2.6
 619  */
 620 U_STABLE int32_t U_EXPORT2
 621 uidna_toUnicode(const UChar* src, int32_t srcLength,
 622                 UChar* dest, int32_t destCapacity,
 623                 int32_t options,
 624                 UParseError* parseError,
 625                 UErrorCode* status);
 626
 627
 628 /**
 629  * IDNA2003: Convenience function that implements the IDNToASCII operation as defined in the IDNA RFC.
 630  * This operation is done on complete domain names, e.g: "www.example.com".
 631  * It is important to note that this operation can fail. If it fails, then the input
 632  * domain name cannot be used as an Internationalized Domain Name and the application
 633  * should have methods defined to deal with the failure.
 634  *
 635  * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name
 636  * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each,
 637  * and then convert. This function does not offer that level of granularity. The options once
 638  * set will apply to all labels in the domain name
 639  *
 640  * @param src               Input UChar array containing IDN in Unicode.
 641  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 642  * @param dest              Output UChar array with ASCII (ACE encoded) IDN.
 643  * @param destCapacity      Size of dest.
 644  * @param options           A bit set of options:
 645  *
 646  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 647  *                              and do not use STD3 ASCII rules
 648  *                              If unassigned code points are found the operation fails with
 649  *                              U_UNASSIGNED_CODE_POINT_FOUND error code.
 650  *
 651  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
 652  *                              If this option is set, the unassigned code points are in the input
 653  *                              are treated as normal Unicode code points.
 654  *
 655  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 656  *                              If this option is set and the input does not satisfy STD3 rules,
 657  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 658  *
 659  * @param parseError        Pointer to UParseError struct to receive information on position
 660  *                          of error if an error is encountered. Can be NULL.
 661  * @param status            ICU in/out error code parameter.
 662  *                          U_INVALID_CHAR_FOUND if src contains
 663  *                          unmatched single surrogates.
 664  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 665  *                          too many code points.
 666  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 667  * @return The length of the result string, if successful - or in case of a buffer overflow,
 668  *         in which case it will be greater than destCapacity.
 669  * @stable ICU 2.6
 670  */
 671 U_STABLE int32_t U_EXPORT2
 672 uidna_IDNToASCII(  const UChar* src, int32_t srcLength,
 673                    UChar* dest, int32_t destCapacity,
 674                    int32_t options,
 675                    UParseError* parseError,
 676                    UErrorCode* status);
 677
 678 /**
 679  * IDNA2003: Convenience function that implements the IDNToUnicode operation as defined in the IDNA RFC.
 680  * This operation is done on complete domain names, e.g: "www.example.com".
 681  *
 682  * <b>Note:</b> IDNA RFC specifies that a conformant application should divide a domain name
 683  * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each,
 684  * and then convert. This function does not offer that level of granularity. The options once
 685  * set will apply to all labels in the domain name
 686  *
 687  * @param src               Input UChar array containing IDN in ASCII (ACE encoded) form.
 688  * @param srcLength         Number of UChars in src, or -1 if NUL-terminated.
 689  * @param dest Output       UChar array containing Unicode equivalent of source IDN.
 690  * @param destCapacity      Size of dest.
 691  * @param options           A bit set of options:
 692  *
 693  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 694  *                              and do not use STD3 ASCII rules
 695  *                              If unassigned code points are found the operation fails with
 696  *                              U_UNASSIGNED_CODE_POINT_FOUND error code.
 697  *
 698  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
 699  *                              If this option is set, the unassigned code points are in the input
 700  *                              are treated as normal Unicode code points.
 701  *
 702  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 703  *                              If this option is set and the input does not satisfy STD3 rules,
 704  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 705  *
 706  * @param parseError        Pointer to UParseError struct to receive information on position
 707  *                          of error if an error is encountered. Can be NULL.
 708  * @param status            ICU in/out error code parameter.
 709  *                          U_INVALID_CHAR_FOUND if src contains
 710  *                          unmatched single surrogates.
 711  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
 712  *                          too many code points.
 713  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
 714  * @return The length of the result string, if successful - or in case of a buffer overflow,
 715  *         in which case it will be greater than destCapacity.
 716  * @stable ICU 2.6
 717  */
 718 U_STABLE int32_t U_EXPORT2
 719 uidna_IDNToUnicode(  const UChar* src, int32_t srcLength,
 720                      UChar* dest, int32_t destCapacity,
 721                      int32_t options,
 722                      UParseError* parseError,
 723                      UErrorCode* status);
 724
 725 /**
 726  * IDNA2003: Compare two IDN strings for equivalence.
 727  * This function splits the domain names into labels and compares them.
 728  * According to IDN RFC, whenever two labels are compared, they are
 729  * considered equal if and only if their ASCII forms (obtained by
 730  * applying toASCII) match using an case-insensitive ASCII comparison.
 731  * Two domain names are considered a match if and only if all labels
 732  * match regardless of whether label separators match.
 733  *
 734  * @param s1                First source string.
 735  * @param length1           Length of first source string, or -1 if NUL-terminated.
 736  *
 737  * @param s2                Second source string.
 738  * @param length2           Length of second source string, or -1 if NUL-terminated.
 739  * @param options           A bit set of options:
 740  *
 741  *  - UIDNA_DEFAULT             Use default options, i.e., do not process unassigned code points
 742  *                              and do not use STD3 ASCII rules
 743  *                              If unassigned code points are found the operation fails with
 744  *                              U_UNASSIGNED_CODE_POINT_FOUND error code.
 745  *
 746  *  - UIDNA_ALLOW_UNASSIGNED    Unassigned values can be converted to ASCII for query operations
 747  *                              If this option is set, the unassigned code points are in the input
 748  *                              are treated as normal Unicode code points.
 749  *
 750  *  - UIDNA_USE_STD3_RULES      Use STD3 ASCII rules for host name syntax restrictions
 751  *                              If this option is set and the input does not satisfy STD3 rules,
 752  *                              the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR
 753  *
 754  * @param status            ICU error code in/out parameter.
 755  *                          Must fulfill U_SUCCESS before the function call.
 756  * @return <0 or 0 or >0 as usual for string comparisons
 757  * @stable ICU 2.6
 758  */
 759 U_STABLE int32_t U_EXPORT2
 760 uidna_compare(  const UChar *s1, int32_t length1,
 761                 const UChar *s2, int32_t length2,
 762                 int32_t options,
 763                 UErrorCode* status);
 764
 765 #endif /* #if !UCONFIG_NO_IDNA */
 766
 767 #endif