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