1 /* 2 ******************************************************************************* 3 * Copyright (C) 2010, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ******************************************************************************* 6 * file name: idna.h 7 * encoding: US-ASCII 8 * tab size: 8 (not used) 9 * indentation:4 10 * 11 * created on: 2010mar05 12 * created by: Markus W. Scherer 13 */ 14 15 #ifndef __IDNA_H__ 16 #define __IDNA_H__ 17 18 /** 19 * \file 20 * \brief C++ API: Internationalizing Domain Names in Applications (IDNA) 21 */ 22 23 #include "unicode/utypes.h" 24 25 #if !UCONFIG_NO_IDNA 26 27 #include "unicode/bytestream.h" 28 #include "unicode/stringpiece.h" 29 #include "unicode/uidna.h" 30 #include "unicode/unistr.h" 31 32 U_NAMESPACE_BEGIN 33 34 class U_COMMON_API IDNAInfo; 35 36 /** 37 * Abstract base class for IDNA processing. 38 * See http://www.unicode.org/reports/tr46/ 39 * and http://www.ietf.org/rfc/rfc3490.txt 40 * 41 * The IDNA class is not intended for public subclassing. 42 * 43 * This C++ API currently only implements UTS #46. 44 * The uidna.h C API implements both UTS #46 (functions using UIDNA service object) 45 * and IDNA2003 (functions that do not use a service object). 46 * @draft ICU 4.6 47 */ 48 class U_COMMON_API IDNA : public UObject { 49 public: 50 /** 51 * Returns an IDNA instance which implements UTS #46. 52 * Returns an unmodifiable instance, owned by the caller. 53 * Cache it for multiple operations, and delete it when done. 54 * The instance is thread-safe, that is, it can be used concurrently. 55 * 56 * UTS #46 defines Unicode IDNA Compatibility Processing, 57 * updated to the latest version of Unicode and compatible with both 58 * IDNA2003 and IDNA2008. 59 * 60 * The worker functions use transitional processing, including deviation mappings, 61 * unless UIDNA_NONTRANSITIONAL_TO_ASCII or UIDNA_NONTRANSITIONAL_TO_UNICODE 62 * is used in which case the deviation characters are passed through without change. 63 * 64 * Disallowed characters are mapped to U+FFFD. 65 * 66 * For available options see the uidna.h header. 67 * Operations with the UTS #46 instance do not support the 68 * UIDNA_ALLOW_UNASSIGNED option. 69 * 70 * By default, the UTS #46 implementation allows all ASCII characters (as valid or mapped). 71 * When the UIDNA_USE_STD3_RULES option is used, ASCII characters other than 72 * letters, digits, hyphen (LDH) and dot/full stop are disallowed and mapped to U+FFFD. 73 * 74 * @param options Bit set to modify the processing and error checking. 75 * See option bit set values in uidna.h. 76 * @param errorCode Standard ICU error code. Its input value must 77 * pass the U_SUCCESS() test, or else the function returns 78 * immediately. Check for U_FAILURE() on output or use with 79 * function chaining. (See User Guide for details.) 80 * @return the UTS #46 IDNA instance, if successful 81 * @draft ICU 4.6 82 */ 83 static IDNA * 84 createUTS46Instance(uint32_t options, UErrorCode &errorCode); 85 86 /** 87 * Converts a single domain name label into its ASCII form for DNS lookup. 88 * If any processing step fails, then info.hasErrors() will be TRUE and 89 * the result might not be an ASCII string. 90 * The label might be modified according to the types of errors. 91 * Labels with severe errors will be left in (or turned into) their Unicode form. 92 * 93 * The UErrorCode indicates an error only in exceptional cases, 94 * such as a U_MEMORY_ALLOCATION_ERROR. 95 * 96 * @param label Input domain name label 97 * @param dest Destination string object 98 * @param info Output container of IDNA processing details. 99 * @param errorCode Standard ICU error code. Its input value must 100 * pass the U_SUCCESS() test, or else the function returns 101 * immediately. Check for U_FAILURE() on output or use with 102 * function chaining. (See User Guide for details.) 103 * @return dest 104 * @draft ICU 4.6 105 */ 106 virtual UnicodeString & 107 labelToASCII(const UnicodeString &label, UnicodeString &dest, 108 IDNAInfo &info, UErrorCode &errorCode) const = 0; 109 110 /** 111 * Converts a single domain name label into its Unicode form for human-readable display. 112 * If any processing step fails, then info.hasErrors() will be TRUE. 113 * The label might be modified according to the types of errors. 114 * 115 * The UErrorCode indicates an error only in exceptional cases, 116 * such as a U_MEMORY_ALLOCATION_ERROR. 117 * 118 * @param label Input domain name label 119 * @param dest Destination string object 120 * @param info Output container of IDNA processing details. 121 * @param errorCode Standard ICU error code. Its input value must 122 * pass the U_SUCCESS() test, or else the function returns 123 * immediately. Check for U_FAILURE() on output or use with 124 * function chaining. (See User Guide for details.) 125 * @return dest 126 * @draft ICU 4.6 127 */ 128 virtual UnicodeString & 129 labelToUnicode(const UnicodeString &label, UnicodeString &dest, 130 IDNAInfo &info, UErrorCode &errorCode) const = 0; 131 132 /** 133 * Converts a whole domain name into its ASCII form for DNS lookup. 134 * If any processing step fails, then info.hasErrors() will be TRUE and 135 * the result might not be an ASCII string. 136 * The domain name might be modified according to the types of errors. 137 * Labels with severe errors will be left in (or turned into) their Unicode form. 138 * 139 * The UErrorCode indicates an error only in exceptional cases, 140 * such as a U_MEMORY_ALLOCATION_ERROR. 141 * 142 * @param name Input domain name 143 * @param dest Destination string object 144 * @param info Output container of IDNA processing details. 145 * @param errorCode Standard ICU error code. Its input value must 146 * pass the U_SUCCESS() test, or else the function returns 147 * immediately. Check for U_FAILURE() on output or use with 148 * function chaining. (See User Guide for details.) 149 * @return dest 150 * @draft ICU 4.6 151 */ 152 virtual UnicodeString & 153 nameToASCII(const UnicodeString &name, UnicodeString &dest, 154 IDNAInfo &info, UErrorCode &errorCode) const = 0; 155 156 /** 157 * Converts a whole domain name into its Unicode form for human-readable display. 158 * If any processing step fails, then info.hasErrors() will be TRUE. 159 * The domain name might be modified according to the types of errors. 160 * 161 * The UErrorCode indicates an error only in exceptional cases, 162 * such as a U_MEMORY_ALLOCATION_ERROR. 163 * 164 * @param name Input domain name 165 * @param dest Destination string object 166 * @param info Output container of IDNA processing details. 167 * @param errorCode Standard ICU error code. Its input value must 168 * pass the U_SUCCESS() test, or else the function returns 169 * immediately. Check for U_FAILURE() on output or use with 170 * function chaining. (See User Guide for details.) 171 * @return dest 172 * @draft ICU 4.6 173 */ 174 virtual UnicodeString & 175 nameToUnicode(const UnicodeString &name, UnicodeString &dest, 176 IDNAInfo &info, UErrorCode &errorCode) const = 0; 177 178 // UTF-8 versions of the processing methods ---------------------------- *** 179 180 /** 181 * Converts a single domain name label into its ASCII form for DNS lookup. 182 * UTF-8 version of labelToASCII(), same behavior. 183 * 184 * @param label Input domain name label 185 * @param dest Destination byte sink; Flush()ed if successful 186 * @param info Output container of IDNA processing details. 187 * @param errorCode Standard ICU error code. Its input value must 188 * pass the U_SUCCESS() test, or else the function returns 189 * immediately. Check for U_FAILURE() on output or use with 190 * function chaining. (See User Guide for details.) 191 * @return dest 192 * @draft ICU 4.6 193 */ 194 virtual void 195 labelToASCII_UTF8(const StringPiece &label, ByteSink &dest, 196 IDNAInfo &info, UErrorCode &errorCode) const; 197 198 /** 199 * Converts a single domain name label into its Unicode form for human-readable display. 200 * UTF-8 version of labelToUnicode(), same behavior. 201 * 202 * @param label Input domain name label 203 * @param dest Destination byte sink; Flush()ed if successful 204 * @param info Output container of IDNA processing details. 205 * @param errorCode Standard ICU error code. Its input value must 206 * pass the U_SUCCESS() test, or else the function returns 207 * immediately. Check for U_FAILURE() on output or use with 208 * function chaining. (See User Guide for details.) 209 * @return dest 210 * @draft ICU 4.6 211 */ 212 virtual void 213 labelToUnicodeUTF8(const StringPiece &label, ByteSink &dest, 214 IDNAInfo &info, UErrorCode &errorCode) const; 215 216 /** 217 * Converts a whole domain name into its ASCII form for DNS lookup. 218 * UTF-8 version of nameToASCII(), same behavior. 219 * 220 * @param name Input domain name 221 * @param dest Destination byte sink; Flush()ed if successful 222 * @param info Output container of IDNA processing details. 223 * @param errorCode Standard ICU error code. Its input value must 224 * pass the U_SUCCESS() test, or else the function returns 225 * immediately. Check for U_FAILURE() on output or use with 226 * function chaining. (See User Guide for details.) 227 * @return dest 228 * @draft ICU 4.6 229 */ 230 virtual void 231 nameToASCII_UTF8(const StringPiece &name, ByteSink &dest, 232 IDNAInfo &info, UErrorCode &errorCode) const; 233 234 /** 235 * Converts a whole domain name into its Unicode form for human-readable display. 236 * UTF-8 version of nameToUnicode(), same behavior. 237 * 238 * @param name Input domain name 239 * @param dest Destination byte sink; Flush()ed if successful 240 * @param info Output container of IDNA processing details. 241 * @param errorCode Standard ICU error code. Its input value must 242 * pass the U_SUCCESS() test, or else the function returns 243 * immediately. Check for U_FAILURE() on output or use with 244 * function chaining. (See User Guide for details.) 245 * @return dest 246 * @draft ICU 4.6 247 */ 248 virtual void 249 nameToUnicodeUTF8(const StringPiece &name, ByteSink &dest, 250 IDNAInfo &info, UErrorCode &errorCode) const; 251 252 private: 253 // No ICU "poor man's RTTI" for this class nor its subclasses. 254 virtual UClassID getDynamicClassID() const; 255 }; 256 257 class UTS46; 258 259 /** 260 * Output container for IDNA processing errors. 261 * The IDNAInfo class is not suitable for subclassing. 262 * @draft ICU 4.6 263 */ 264 class U_COMMON_API IDNAInfo : public UMemory { 265 public: 266 /** 267 * Constructor for stack allocation. 268 * @draft ICU 4.6 269 */ 270 IDNAInfo() : errors(0), labelErrors(0), isTransDiff(FALSE), isBiDi(FALSE), isOkBiDi(TRUE) {} 271 /** 272 * Were there IDNA processing errors? 273 * @return TRUE if there were processing errors 274 * @draft ICU 4.6 275 */ 276 UBool hasErrors() const { return errors!=0; } 277 /** 278 * Returns a bit set indicating IDNA processing errors. 279 * See UIDNA_ERROR_... constants in uidna.h. 280 * @return bit set of processing errors 281 * @draft ICU 4.6 282 */ 283 uint32_t getErrors() const { return errors; } 284 /** 285 * Returns TRUE if transitional and nontransitional processing produce different results. 286 * This is the case when the input label or domain name contains 287 * one or more deviation characters outside a Punycode label (see UTS #46). 288 * <ul> 289 * <li>With nontransitional processing, such characters are 290 * copied to the destination string. 291 * <li>With transitional processing, such characters are 292 * mapped (sharp s/sigma) or removed (joiner/nonjoiner). 293 * </ul> 294 * @return TRUE if transitional and nontransitional processing produce different results 295 * @draft ICU 4.6 296 */ 297 UBool isTransitionalDifferent() const { return isTransDiff; } 298 299 private: 300 friend class UTS46; 301 302 IDNAInfo(const IDNAInfo &other); // no copying 303 IDNAInfo &operator=(const IDNAInfo &other); // no copying 304 305 void reset() { 306 errors=labelErrors=0; 307 isTransDiff=FALSE; 308 isBiDi=FALSE; 309 isOkBiDi=TRUE; 310 } 311 312 uint32_t errors, labelErrors; 313 UBool isTransDiff; 314 UBool isBiDi; 315 UBool isOkBiDi; 316 }; 317 318 U_NAMESPACE_END 319 320 #endif // UCONFIG_NO_IDNA 321 #endif // __IDNA_H__ 322
