icuSources/common/unicode/uidna.h

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