jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ******************************************************************************* jpayne@69: * Copyright (C) 2010-2012, International Business Machines jpayne@69: * Corporation and others. All Rights Reserved. jpayne@69: ******************************************************************************* jpayne@69: * file name: idna.h jpayne@69: * encoding: UTF-8 jpayne@69: * tab size: 8 (not used) jpayne@69: * indentation:4 jpayne@69: * jpayne@69: * created on: 2010mar05 jpayne@69: * created by: Markus W. Scherer jpayne@69: */ jpayne@69: jpayne@69: #ifndef __IDNA_H__ jpayne@69: #define __IDNA_H__ jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C++ API: Internationalizing Domain Names in Applications (IDNA) jpayne@69: */ jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: #if !UCONFIG_NO_IDNA jpayne@69: jpayne@69: #include "unicode/bytestream.h" jpayne@69: #include "unicode/stringpiece.h" jpayne@69: #include "unicode/uidna.h" jpayne@69: #include "unicode/unistr.h" jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: class IDNAInfo; jpayne@69: jpayne@69: /** jpayne@69: * Abstract base class for IDNA processing. jpayne@69: * See http://www.unicode.org/reports/tr46/ jpayne@69: * and http://www.ietf.org/rfc/rfc3490.txt jpayne@69: * jpayne@69: * The IDNA class is not intended for public subclassing. jpayne@69: * jpayne@69: * This C++ API currently only implements UTS #46. jpayne@69: * The uidna.h C API implements both UTS #46 (functions using UIDNA service object) jpayne@69: * and IDNA2003 (functions that do not use a service object). jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: class U_COMMON_API IDNA : public UObject { jpayne@69: public: jpayne@69: /** jpayne@69: * Destructor. jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: ~IDNA(); jpayne@69: jpayne@69: /** jpayne@69: * Returns an IDNA instance which implements UTS #46. jpayne@69: * Returns an unmodifiable instance, owned by the caller. jpayne@69: * Cache it for multiple operations, and delete it when done. jpayne@69: * The instance is thread-safe, that is, it can be used concurrently. jpayne@69: * jpayne@69: * UTS #46 defines Unicode IDNA Compatibility Processing, jpayne@69: * updated to the latest version of Unicode and compatible with both jpayne@69: * IDNA2003 and IDNA2008. jpayne@69: * jpayne@69: * The worker functions use transitional processing, including deviation mappings, jpayne@69: * unless UIDNA_NONTRANSITIONAL_TO_ASCII or UIDNA_NONTRANSITIONAL_TO_UNICODE jpayne@69: * is used in which case the deviation characters are passed through without change. jpayne@69: * jpayne@69: * Disallowed characters are mapped to U+FFFD. jpayne@69: * jpayne@69: * For available options see the uidna.h header. jpayne@69: * Operations with the UTS #46 instance do not support the jpayne@69: * UIDNA_ALLOW_UNASSIGNED option. jpayne@69: * jpayne@69: * By default, the UTS #46 implementation allows all ASCII characters (as valid or mapped). jpayne@69: * When the UIDNA_USE_STD3_RULES option is used, ASCII characters other than jpayne@69: * letters, digits, hyphen (LDH) and dot/full stop are disallowed and mapped to U+FFFD. jpayne@69: * jpayne@69: * @param options Bit set to modify the processing and error checking. jpayne@69: * See option bit set values in uidna.h. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return the UTS #46 IDNA instance, if successful jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: static IDNA * jpayne@69: createUTS46Instance(uint32_t options, UErrorCode &errorCode); jpayne@69: jpayne@69: /** jpayne@69: * Converts a single domain name label into its ASCII form for DNS lookup. jpayne@69: * If any processing step fails, then info.hasErrors() will be TRUE and jpayne@69: * the result might not be an ASCII string. jpayne@69: * The label might be modified according to the types of errors. jpayne@69: * Labels with severe errors will be left in (or turned into) their Unicode form. jpayne@69: * jpayne@69: * The UErrorCode indicates an error only in exceptional cases, jpayne@69: * such as a U_MEMORY_ALLOCATION_ERROR. jpayne@69: * jpayne@69: * @param label Input domain name label jpayne@69: * @param dest Destination string object jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual UnicodeString & jpayne@69: labelToASCII(const UnicodeString &label, UnicodeString &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Converts a single domain name label into its Unicode form for human-readable display. jpayne@69: * If any processing step fails, then info.hasErrors() will be TRUE. jpayne@69: * The label might be modified according to the types of errors. jpayne@69: * jpayne@69: * The UErrorCode indicates an error only in exceptional cases, jpayne@69: * such as a U_MEMORY_ALLOCATION_ERROR. jpayne@69: * jpayne@69: * @param label Input domain name label jpayne@69: * @param dest Destination string object jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual UnicodeString & jpayne@69: labelToUnicode(const UnicodeString &label, UnicodeString &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Converts a whole domain name into its ASCII form for DNS lookup. jpayne@69: * If any processing step fails, then info.hasErrors() will be TRUE and jpayne@69: * the result might not be an ASCII string. jpayne@69: * The domain name might be modified according to the types of errors. jpayne@69: * Labels with severe errors will be left in (or turned into) their Unicode form. jpayne@69: * jpayne@69: * The UErrorCode indicates an error only in exceptional cases, jpayne@69: * such as a U_MEMORY_ALLOCATION_ERROR. jpayne@69: * jpayne@69: * @param name Input domain name jpayne@69: * @param dest Destination string object jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual UnicodeString & jpayne@69: nameToASCII(const UnicodeString &name, UnicodeString &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Converts a whole domain name into its Unicode form for human-readable display. jpayne@69: * If any processing step fails, then info.hasErrors() will be TRUE. jpayne@69: * The domain name might be modified according to the types of errors. jpayne@69: * jpayne@69: * The UErrorCode indicates an error only in exceptional cases, jpayne@69: * such as a U_MEMORY_ALLOCATION_ERROR. jpayne@69: * jpayne@69: * @param name Input domain name jpayne@69: * @param dest Destination string object jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual UnicodeString & jpayne@69: nameToUnicode(const UnicodeString &name, UnicodeString &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const = 0; jpayne@69: jpayne@69: // UTF-8 versions of the processing methods ---------------------------- *** jpayne@69: jpayne@69: /** jpayne@69: * Converts a single domain name label into its ASCII form for DNS lookup. jpayne@69: * UTF-8 version of labelToASCII(), same behavior. jpayne@69: * jpayne@69: * @param label Input domain name label jpayne@69: * @param dest Destination byte sink; Flush()ed if successful jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual void jpayne@69: labelToASCII_UTF8(StringPiece label, ByteSink &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const; jpayne@69: jpayne@69: /** jpayne@69: * Converts a single domain name label into its Unicode form for human-readable display. jpayne@69: * UTF-8 version of labelToUnicode(), same behavior. jpayne@69: * jpayne@69: * @param label Input domain name label jpayne@69: * @param dest Destination byte sink; Flush()ed if successful jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual void jpayne@69: labelToUnicodeUTF8(StringPiece label, ByteSink &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const; jpayne@69: jpayne@69: /** jpayne@69: * Converts a whole domain name into its ASCII form for DNS lookup. jpayne@69: * UTF-8 version of nameToASCII(), same behavior. jpayne@69: * jpayne@69: * @param name Input domain name jpayne@69: * @param dest Destination byte sink; Flush()ed if successful jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual void jpayne@69: nameToASCII_UTF8(StringPiece name, ByteSink &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const; jpayne@69: jpayne@69: /** jpayne@69: * Converts a whole domain name into its Unicode form for human-readable display. jpayne@69: * UTF-8 version of nameToUnicode(), same behavior. jpayne@69: * jpayne@69: * @param name Input domain name jpayne@69: * @param dest Destination byte sink; Flush()ed if successful jpayne@69: * @param info Output container of IDNA processing details. jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return dest jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: virtual void jpayne@69: nameToUnicodeUTF8(StringPiece name, ByteSink &dest, jpayne@69: IDNAInfo &info, UErrorCode &errorCode) const; jpayne@69: }; jpayne@69: jpayne@69: class UTS46; jpayne@69: jpayne@69: /** jpayne@69: * Output container for IDNA processing errors. jpayne@69: * The IDNAInfo class is not suitable for subclassing. jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: class U_COMMON_API IDNAInfo : public UMemory { jpayne@69: public: jpayne@69: /** jpayne@69: * Constructor for stack allocation. jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: IDNAInfo() : errors(0), labelErrors(0), isTransDiff(FALSE), isBiDi(FALSE), isOkBiDi(TRUE) {} jpayne@69: /** jpayne@69: * Were there IDNA processing errors? jpayne@69: * @return TRUE if there were processing errors jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: UBool hasErrors() const { return errors!=0; } jpayne@69: /** jpayne@69: * Returns a bit set indicating IDNA processing errors. jpayne@69: * See UIDNA_ERROR_... constants in uidna.h. jpayne@69: * @return bit set of processing errors jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: uint32_t getErrors() const { return errors; } jpayne@69: /** jpayne@69: * Returns TRUE if transitional and nontransitional processing produce different results. jpayne@69: * This is the case when the input label or domain name contains jpayne@69: * one or more deviation characters outside a Punycode label (see UTS #46). jpayne@69: * jpayne@69: * @return TRUE if transitional and nontransitional processing produce different results jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: UBool isTransitionalDifferent() const { return isTransDiff; } jpayne@69: jpayne@69: private: jpayne@69: friend class UTS46; jpayne@69: jpayne@69: IDNAInfo(const IDNAInfo &other); // no copying jpayne@69: IDNAInfo &operator=(const IDNAInfo &other); // no copying jpayne@69: jpayne@69: void reset() { jpayne@69: errors=labelErrors=0; jpayne@69: isTransDiff=FALSE; jpayne@69: isBiDi=FALSE; jpayne@69: isOkBiDi=TRUE; jpayne@69: } jpayne@69: jpayne@69: uint32_t errors, labelErrors; jpayne@69: UBool isTransDiff; jpayne@69: UBool isBiDi; jpayne@69: UBool isOkBiDi; jpayne@69: }; jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif // UCONFIG_NO_IDNA jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif // __IDNA_H__