icuSources/common/unicode/uidna.h

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