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 734
