This option is ignored by the UTS46 implementation. michael@0: * (UTS #46 disallows unassigned code points.) michael@0: * @stable ICU 2.6 michael@0: */ michael@0: UIDNA_ALLOW_UNASSIGNED=1, michael@0: /** michael@0: * Option to check whether the input conforms to the STD3 ASCII rules, michael@0: * for example the restriction of labels to LDH characters michael@0: * (ASCII Letters, Digits and Hyphen-Minus). michael@0: * For use in static worker and factory methods. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: UIDNA_USE_STD3_RULES=2, michael@0: /** michael@0: * IDNA option to check for whether the input conforms to the BiDi rules. michael@0: * For use in static worker and factory methods. michael@0: *
This option is ignored by the IDNA2003 implementation. michael@0: * (IDNA2003 always performs a BiDi check.) michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_CHECK_BIDI=4, michael@0: /** michael@0: * IDNA option to check for whether the input conforms to the CONTEXTJ rules. michael@0: * For use in static worker and factory methods. michael@0: *
This option is ignored by the IDNA2003 implementation. michael@0: * (The CONTEXTJ check is new in IDNA2008.) michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_CHECK_CONTEXTJ=8, michael@0: /** michael@0: * IDNA option for nontransitional processing in ToASCII(). michael@0: * For use in static worker and factory methods. michael@0: *
By default, ToASCII() uses transitional processing. michael@0: *
This option is ignored by the IDNA2003 implementation. michael@0: * (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.) michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_NONTRANSITIONAL_TO_ASCII=0x10, michael@0: /** michael@0: * IDNA option for nontransitional processing in ToUnicode(). michael@0: * For use in static worker and factory methods. michael@0: *
By default, ToUnicode() uses transitional processing. michael@0: *
This option is ignored by the IDNA2003 implementation. michael@0: * (This is only relevant for compatibility of newer IDNA implementations with IDNA2003.) michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_NONTRANSITIONAL_TO_UNICODE=0x20, michael@0: /** michael@0: * IDNA option to check for whether the input conforms to the CONTEXTO rules. michael@0: * For use in static worker and factory methods. michael@0: *
This option is ignored by the IDNA2003 implementation. michael@0: * (The CONTEXTO check is new in IDNA2008.) michael@0: *
This is for use by registries for IDNA2008 conformance. michael@0: * UTS #46 does not require the CONTEXTO check. michael@0: * @stable ICU 49 michael@0: */ michael@0: UIDNA_CHECK_CONTEXTO=0x40 michael@0: }; michael@0: michael@0: /** michael@0: * Opaque C service object type for the new IDNA API. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: struct UIDNA; michael@0: typedef struct UIDNA UIDNA; /**< C typedef for struct UIDNA. @stable ICU 4.6 */ michael@0: michael@0: /** michael@0: * Returns a UIDNA instance which implements UTS #46. michael@0: * Returns an unmodifiable instance, owned by the caller. michael@0: * Cache it for multiple operations, and uidna_close() it when done. michael@0: * The instance is thread-safe, that is, it can be used concurrently. michael@0: * michael@0: * For details about the UTS #46 implementation see the IDNA C++ class in idna.h. michael@0: * michael@0: * @param options Bit set to modify the processing and error checking. michael@0: * See option bit set values in uidna.h. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return the UTS #46 UIDNA instance, if successful michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE UIDNA * U_EXPORT2 michael@0: uidna_openUTS46(uint32_t options, UErrorCode *pErrorCode); michael@0: michael@0: /** michael@0: * Closes a UIDNA instance. michael@0: * @param idna UIDNA instance to be closed michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: uidna_close(UIDNA *idna); michael@0: michael@0: #if U_SHOW_CPLUSPLUS_API michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: /** michael@0: * \class LocalUIDNAPointer michael@0: * "Smart pointer" class, closes a UIDNA via uidna_close(). michael@0: * For most methods see the LocalPointerBase base class. michael@0: * michael@0: * @see LocalPointerBase michael@0: * @see LocalPointer michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUIDNAPointer, UIDNA, uidna_close); michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif michael@0: michael@0: /** michael@0: * Output container for IDNA processing errors. michael@0: * Initialize with UIDNA_INFO_INITIALIZER: michael@0: * \code michael@0: * UIDNAInfo info = UIDNA_INFO_INITIALIZER; michael@0: * int32_t length = uidna_nameToASCII(..., &info, &errorCode); michael@0: * if(U_SUCCESS(errorCode) && info.errors!=0) { ... } michael@0: * \endcode michael@0: * @stable ICU 4.6 michael@0: */ michael@0: typedef struct UIDNAInfo { michael@0: /** sizeof(UIDNAInfo) @stable ICU 4.6 */ michael@0: int16_t size; michael@0: /** michael@0: * Set to TRUE if transitional and nontransitional processing produce different results. michael@0: * For details see C++ IDNAInfo::isTransitionalDifferent(). michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UBool isTransitionalDifferent; michael@0: UBool reservedB3; /**< Reserved field, do not use. @internal */ michael@0: /** michael@0: * Bit set indicating IDNA processing errors. 0 if no errors. michael@0: * See UIDNA_ERROR_... constants. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: uint32_t errors; michael@0: int32_t reservedI2; /**< Reserved field, do not use. @internal */ michael@0: int32_t reservedI3; /**< Reserved field, do not use. @internal */ michael@0: } UIDNAInfo; michael@0: michael@0: /** michael@0: * Static initializer for a UIDNAInfo struct. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: #define UIDNA_INFO_INITIALIZER { \ michael@0: (int16_t)sizeof(UIDNAInfo), \ michael@0: FALSE, FALSE, \ michael@0: 0, 0, 0 } michael@0: michael@0: /** michael@0: * Converts a single domain name label into its ASCII form for DNS lookup. michael@0: * If any processing step fails, then pInfo->errors will be non-zero and michael@0: * the result might not be an ASCII string. michael@0: * The label might be modified according to the types of errors. michael@0: * Labels with severe errors will be left in (or turned into) their Unicode form. michael@0: * michael@0: * The UErrorCode indicates an error only in exceptional cases, michael@0: * such as a U_MEMORY_ALLOCATION_ERROR. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param label Input domain name label michael@0: * @param length Label length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_labelToASCII(const UIDNA *idna, michael@0: const UChar *label, int32_t length, michael@0: UChar *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /** michael@0: * Converts a single domain name label into its Unicode form for human-readable display. michael@0: * If any processing step fails, then pInfo->errors will be non-zero. michael@0: * The label might be modified according to the types of errors. michael@0: * michael@0: * The UErrorCode indicates an error only in exceptional cases, michael@0: * such as a U_MEMORY_ALLOCATION_ERROR. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param label Input domain name label michael@0: * @param length Label length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_labelToUnicode(const UIDNA *idna, michael@0: const UChar *label, int32_t length, michael@0: UChar *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /** michael@0: * Converts a whole domain name into its ASCII form for DNS lookup. michael@0: * If any processing step fails, then pInfo->errors will be non-zero and michael@0: * the result might not be an ASCII string. michael@0: * The domain name might be modified according to the types of errors. michael@0: * Labels with severe errors will be left in (or turned into) their Unicode form. michael@0: * michael@0: * The UErrorCode indicates an error only in exceptional cases, michael@0: * such as a U_MEMORY_ALLOCATION_ERROR. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param name Input domain name michael@0: * @param length Domain name length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_nameToASCII(const UIDNA *idna, michael@0: const UChar *name, int32_t length, michael@0: UChar *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /** michael@0: * Converts a whole domain name into its Unicode form for human-readable display. michael@0: * If any processing step fails, then pInfo->errors will be non-zero. michael@0: * The domain name might be modified according to the types of errors. michael@0: * michael@0: * The UErrorCode indicates an error only in exceptional cases, michael@0: * such as a U_MEMORY_ALLOCATION_ERROR. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param name Input domain name michael@0: * @param length Domain name length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_nameToUnicode(const UIDNA *idna, michael@0: const UChar *name, int32_t length, michael@0: UChar *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /* UTF-8 versions of the processing methods --------------------------------- */ michael@0: michael@0: /** michael@0: * Converts a single domain name label into its ASCII form for DNS lookup. michael@0: * UTF-8 version of uidna_labelToASCII(), same behavior. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param label Input domain name label michael@0: * @param length Label length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_labelToASCII_UTF8(const UIDNA *idna, michael@0: const char *label, int32_t length, michael@0: char *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /** michael@0: * Converts a single domain name label into its Unicode form for human-readable display. michael@0: * UTF-8 version of uidna_labelToUnicode(), same behavior. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param label Input domain name label michael@0: * @param length Label length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_labelToUnicodeUTF8(const UIDNA *idna, michael@0: const char *label, int32_t length, michael@0: char *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /** michael@0: * Converts a whole domain name into its ASCII form for DNS lookup. michael@0: * UTF-8 version of uidna_nameToASCII(), same behavior. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param name Input domain name michael@0: * @param length Domain name length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_nameToASCII_UTF8(const UIDNA *idna, michael@0: const char *name, int32_t length, michael@0: char *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /** michael@0: * Converts a whole domain name into its Unicode form for human-readable display. michael@0: * UTF-8 version of uidna_nameToUnicode(), same behavior. michael@0: * michael@0: * @param idna UIDNA instance michael@0: * @param name Input domain name michael@0: * @param length Domain name length, or -1 if NUL-terminated michael@0: * @param dest Destination string buffer michael@0: * @param capacity Destination buffer capacity michael@0: * @param pInfo Output container of IDNA processing details. michael@0: * @param pErrorCode Standard ICU error code. Its input value must michael@0: * pass the U_SUCCESS() test, or else the function returns michael@0: * immediately. Check for U_FAILURE() on output or use with michael@0: * function chaining. (See User Guide for details.) michael@0: * @return destination string length michael@0: * @stable ICU 4.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_nameToUnicodeUTF8(const UIDNA *idna, michael@0: const char *name, int32_t length, michael@0: char *dest, int32_t capacity, michael@0: UIDNAInfo *pInfo, UErrorCode *pErrorCode); michael@0: michael@0: /* michael@0: * IDNA error bit set values. michael@0: * When a domain name or label fails a processing step or does not meet the michael@0: * validity criteria, then one or more of these error bits are set. michael@0: */ michael@0: enum { michael@0: /** michael@0: * A non-final domain name label (or the whole domain name) is empty. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_EMPTY_LABEL=1, michael@0: /** michael@0: * A domain name label is longer than 63 bytes. michael@0: * (See STD13/RFC1034 3.1. Name space specifications and terminology.) michael@0: * This is only checked in ToASCII operations, and only if the output label is all-ASCII. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_LABEL_TOO_LONG=2, michael@0: /** michael@0: * A domain name is longer than 255 bytes in its storage form. michael@0: * (See STD13/RFC1034 3.1. Name space specifications and terminology.) michael@0: * This is only checked in ToASCII operations, and only if the output domain name is all-ASCII. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_DOMAIN_NAME_TOO_LONG=4, michael@0: /** michael@0: * A label starts with a hyphen-minus ('-'). michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_LEADING_HYPHEN=8, michael@0: /** michael@0: * A label ends with a hyphen-minus ('-'). michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_TRAILING_HYPHEN=0x10, michael@0: /** michael@0: * A label contains hyphen-minus ('-') in the third and fourth positions. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_HYPHEN_3_4=0x20, michael@0: /** michael@0: * A label starts with a combining mark. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_LEADING_COMBINING_MARK=0x40, michael@0: /** michael@0: * A label or domain name contains disallowed characters. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_DISALLOWED=0x80, michael@0: /** michael@0: * A label starts with "xn--" but does not contain valid Punycode. michael@0: * That is, an xn-- label failed Punycode decoding. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_PUNYCODE=0x100, michael@0: /** michael@0: * A label contains a dot=full stop. michael@0: * This can occur in an input string for a single-label function. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_LABEL_HAS_DOT=0x200, michael@0: /** michael@0: * An ACE label does not contain a valid label string. michael@0: * The label was successfully ACE (Punycode) decoded but the resulting michael@0: * string had severe validation errors. For example, michael@0: * it might contain characters that are not allowed in ACE labels, michael@0: * or it might not be normalized. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_INVALID_ACE_LABEL=0x400, michael@0: /** michael@0: * A label does not meet the IDNA BiDi requirements (for right-to-left characters). michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_BIDI=0x800, michael@0: /** michael@0: * A label does not meet the IDNA CONTEXTJ requirements. michael@0: * @stable ICU 4.6 michael@0: */ michael@0: UIDNA_ERROR_CONTEXTJ=0x1000, michael@0: /** michael@0: * A label does not meet the IDNA CONTEXTO requirements for punctuation characters. michael@0: * Some punctuation characters "Would otherwise have been DISALLOWED" michael@0: * but are allowed in certain contexts. (RFC 5892) michael@0: * @stable ICU 49 michael@0: */ michael@0: UIDNA_ERROR_CONTEXTO_PUNCTUATION=0x2000, michael@0: /** michael@0: * A label does not meet the IDNA CONTEXTO requirements for digits. michael@0: * Arabic-Indic Digits (U+066x) must not be mixed with Extended Arabic-Indic Digits (U+06Fx). michael@0: * @stable ICU 49 michael@0: */ michael@0: UIDNA_ERROR_CONTEXTO_DIGITS=0x4000 michael@0: }; michael@0: michael@0: /* IDNA2003 API ------------------------------------------------------------- */ michael@0: michael@0: /** michael@0: * IDNA2003: This function implements the ToASCII operation as defined in the IDNA RFC. michael@0: * This operation is done on single labels before sending it to something that expects michael@0: * ASCII names. A label is an individual part of a domain name. Labels are usually michael@0: * separated by dots; e.g. "www.example.com" is composed of 3 labels "www","example", and "com". michael@0: * michael@0: * IDNA2003 API Overview: michael@0: * michael@0: * The uidna_ API implements the IDNA protocol as defined in the IDNA RFC michael@0: * (http://www.ietf.org/rfc/rfc3490.txt). michael@0: * The RFC defines 2 operations: ToASCII and ToUnicode. Domain name labels michael@0: * containing non-ASCII code points are processed by the michael@0: * ToASCII operation before passing it to resolver libraries. Domain names michael@0: * that are obtained from resolver libraries are processed by the michael@0: * ToUnicode operation before displaying the domain name to the user. michael@0: * IDNA requires that implementations process input strings with Nameprep michael@0: * (http://www.ietf.org/rfc/rfc3491.txt), michael@0: * which is a profile of Stringprep (http://www.ietf.org/rfc/rfc3454.txt), michael@0: * and then with Punycode (http://www.ietf.org/rfc/rfc3492.txt). michael@0: * Implementations of IDNA MUST fully implement Nameprep and Punycode; michael@0: * neither Nameprep nor Punycode are optional. michael@0: * The input and output of ToASCII and ToUnicode operations are Unicode michael@0: * and are designed to be chainable, i.e., applying ToASCII or ToUnicode operations michael@0: * multiple times to an input string will yield the same result as applying the operation michael@0: * once. michael@0: * ToUnicode(ToUnicode(ToUnicode...(ToUnicode(string)))) == ToUnicode(string) michael@0: * ToASCII(ToASCII(ToASCII...(ToASCII(string))) == ToASCII(string). michael@0: * michael@0: * @param src Input UChar array containing label in Unicode. michael@0: * @param srcLength Number of UChars in src, or -1 if NUL-terminated. michael@0: * @param dest Output UChar array with ASCII (ACE encoded) label. michael@0: * @param destCapacity Size of dest. michael@0: * @param options A bit set of options: michael@0: * michael@0: * - UIDNA_DEFAULT Use default options, i.e., do not process unassigned code points michael@0: * and do not use STD3 ASCII rules michael@0: * If unassigned code points are found the operation fails with michael@0: * U_UNASSIGNED_ERROR error code. michael@0: * michael@0: * - UIDNA_ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations michael@0: * If this option is set, the unassigned code points are in the input michael@0: * are treated as normal Unicode code points. michael@0: * michael@0: * - UIDNA_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions michael@0: * If this option is set and the input does not satisfy STD3 rules, michael@0: * the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR michael@0: * michael@0: * @param parseError Pointer to UParseError struct to receive information on position michael@0: * of error if an error is encountered. Can be NULL. michael@0: * @param status ICU in/out error code parameter. michael@0: * U_INVALID_CHAR_FOUND if src contains michael@0: * unmatched single surrogates. michael@0: * U_INDEX_OUTOFBOUNDS_ERROR if src contains michael@0: * too many code points. michael@0: * U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough michael@0: * @return The length of the result string, if successful - or in case of a buffer overflow, michael@0: * in which case it will be greater than destCapacity. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_toASCII(const UChar* src, int32_t srcLength, michael@0: UChar* dest, int32_t destCapacity, michael@0: int32_t options, michael@0: UParseError* parseError, michael@0: UErrorCode* status); michael@0: michael@0: michael@0: /** michael@0: * IDNA2003: This function implements the ToUnicode operation as defined in the IDNA RFC. michael@0: * This operation is done on single labels before sending it to something that expects michael@0: * Unicode names. A label is an individual part of a domain name. Labels are usually michael@0: * separated by dots; for e.g. "www.example.com" is composed of 3 labels "www","example", and "com". michael@0: * michael@0: * @param src Input UChar array containing ASCII (ACE encoded) label. michael@0: * @param srcLength Number of UChars in src, or -1 if NUL-terminated. michael@0: * @param dest Output Converted UChar array containing Unicode equivalent of label. michael@0: * @param destCapacity Size of dest. michael@0: * @param options A bit set of options: michael@0: * michael@0: * - UIDNA_DEFAULT Use default options, i.e., do not process unassigned code points michael@0: * and do not use STD3 ASCII rules michael@0: * If unassigned code points are found the operation fails with michael@0: * U_UNASSIGNED_ERROR error code. michael@0: * michael@0: * - UIDNA_ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations michael@0: * If this option is set, the unassigned code points are in the input michael@0: * are treated as normal Unicode code points. Note: This option is michael@0: * required on toUnicode operation because the RFC mandates michael@0: * verification of decoded ACE input by applying toASCII and comparing michael@0: * its output with source michael@0: * michael@0: * - UIDNA_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions michael@0: * If this option is set and the input does not satisfy STD3 rules, michael@0: * the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR michael@0: * michael@0: * @param parseError Pointer to UParseError struct to receive information on position michael@0: * of error if an error is encountered. Can be NULL. michael@0: * @param status ICU in/out error code parameter. michael@0: * U_INVALID_CHAR_FOUND if src contains michael@0: * unmatched single surrogates. michael@0: * U_INDEX_OUTOFBOUNDS_ERROR if src contains michael@0: * too many code points. michael@0: * U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough michael@0: * @return The length of the result string, if successful - or in case of a buffer overflow, michael@0: * in which case it will be greater than destCapacity. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_toUnicode(const UChar* src, int32_t srcLength, michael@0: UChar* dest, int32_t destCapacity, michael@0: int32_t options, michael@0: UParseError* parseError, michael@0: UErrorCode* status); michael@0: michael@0: michael@0: /** michael@0: * IDNA2003: Convenience function that implements the IDNToASCII operation as defined in the IDNA RFC. michael@0: * This operation is done on complete domain names, e.g: "www.example.com". michael@0: * It is important to note that this operation can fail. If it fails, then the input michael@0: * domain name cannot be used as an Internationalized Domain Name and the application michael@0: * should have methods defined to deal with the failure. michael@0: * michael@0: * Note: IDNA RFC specifies that a conformant application should divide a domain name michael@0: * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, michael@0: * and then convert. This function does not offer that level of granularity. The options once michael@0: * set will apply to all labels in the domain name michael@0: * michael@0: * @param src Input UChar array containing IDN in Unicode. michael@0: * @param srcLength Number of UChars in src, or -1 if NUL-terminated. michael@0: * @param dest Output UChar array with ASCII (ACE encoded) IDN. michael@0: * @param destCapacity Size of dest. michael@0: * @param options A bit set of options: michael@0: * michael@0: * - UIDNA_DEFAULT Use default options, i.e., do not process unassigned code points michael@0: * and do not use STD3 ASCII rules michael@0: * If unassigned code points are found the operation fails with michael@0: * U_UNASSIGNED_CODE_POINT_FOUND error code. michael@0: * michael@0: * - UIDNA_ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations michael@0: * If this option is set, the unassigned code points are in the input michael@0: * are treated as normal Unicode code points. michael@0: * michael@0: * - UIDNA_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions michael@0: * If this option is set and the input does not satisfy STD3 rules, michael@0: * the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR michael@0: * michael@0: * @param parseError Pointer to UParseError struct to receive information on position michael@0: * of error if an error is encountered. Can be NULL. michael@0: * @param status ICU in/out error code parameter. michael@0: * U_INVALID_CHAR_FOUND if src contains michael@0: * unmatched single surrogates. michael@0: * U_INDEX_OUTOFBOUNDS_ERROR if src contains michael@0: * too many code points. michael@0: * U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough michael@0: * @return The length of the result string, if successful - or in case of a buffer overflow, michael@0: * in which case it will be greater than destCapacity. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_IDNToASCII( const UChar* src, int32_t srcLength, michael@0: UChar* dest, int32_t destCapacity, michael@0: int32_t options, michael@0: UParseError* parseError, michael@0: UErrorCode* status); michael@0: michael@0: /** michael@0: * IDNA2003: Convenience function that implements the IDNToUnicode operation as defined in the IDNA RFC. michael@0: * This operation is done on complete domain names, e.g: "www.example.com". michael@0: * michael@0: * Note: IDNA RFC specifies that a conformant application should divide a domain name michael@0: * into separate labels, decide whether to apply allowUnassigned and useSTD3ASCIIRules on each, michael@0: * and then convert. This function does not offer that level of granularity. The options once michael@0: * set will apply to all labels in the domain name michael@0: * michael@0: * @param src Input UChar array containing IDN in ASCII (ACE encoded) form. michael@0: * @param srcLength Number of UChars in src, or -1 if NUL-terminated. michael@0: * @param dest Output UChar array containing Unicode equivalent of source IDN. michael@0: * @param destCapacity Size of dest. michael@0: * @param options A bit set of options: michael@0: * michael@0: * - UIDNA_DEFAULT Use default options, i.e., do not process unassigned code points michael@0: * and do not use STD3 ASCII rules michael@0: * If unassigned code points are found the operation fails with michael@0: * U_UNASSIGNED_CODE_POINT_FOUND error code. michael@0: * michael@0: * - UIDNA_ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations michael@0: * If this option is set, the unassigned code points are in the input michael@0: * are treated as normal Unicode code points. michael@0: * michael@0: * - UIDNA_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions michael@0: * If this option is set and the input does not satisfy STD3 rules, michael@0: * the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR michael@0: * michael@0: * @param parseError Pointer to UParseError struct to receive information on position michael@0: * of error if an error is encountered. Can be NULL. michael@0: * @param status ICU in/out error code parameter. michael@0: * U_INVALID_CHAR_FOUND if src contains michael@0: * unmatched single surrogates. michael@0: * U_INDEX_OUTOFBOUNDS_ERROR if src contains michael@0: * too many code points. michael@0: * U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough michael@0: * @return The length of the result string, if successful - or in case of a buffer overflow, michael@0: * in which case it will be greater than destCapacity. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_IDNToUnicode( const UChar* src, int32_t srcLength, michael@0: UChar* dest, int32_t destCapacity, michael@0: int32_t options, michael@0: UParseError* parseError, michael@0: UErrorCode* status); michael@0: michael@0: /** michael@0: * IDNA2003: Compare two IDN strings for equivalence. michael@0: * This function splits the domain names into labels and compares them. michael@0: * According to IDN RFC, whenever two labels are compared, they are michael@0: * considered equal if and only if their ASCII forms (obtained by michael@0: * applying toASCII) match using an case-insensitive ASCII comparison. michael@0: * Two domain names are considered a match if and only if all labels michael@0: * match regardless of whether label separators match. michael@0: * michael@0: * @param s1 First source string. michael@0: * @param length1 Length of first source string, or -1 if NUL-terminated. michael@0: * michael@0: * @param s2 Second source string. michael@0: * @param length2 Length of second source string, or -1 if NUL-terminated. michael@0: * @param options A bit set of options: michael@0: * michael@0: * - UIDNA_DEFAULT Use default options, i.e., do not process unassigned code points michael@0: * and do not use STD3 ASCII rules michael@0: * If unassigned code points are found the operation fails with michael@0: * U_UNASSIGNED_CODE_POINT_FOUND error code. michael@0: * michael@0: * - UIDNA_ALLOW_UNASSIGNED Unassigned values can be converted to ASCII for query operations michael@0: * If this option is set, the unassigned code points are in the input michael@0: * are treated as normal Unicode code points. michael@0: * michael@0: * - UIDNA_USE_STD3_RULES Use STD3 ASCII rules for host name syntax restrictions michael@0: * If this option is set and the input does not satisfy STD3 rules, michael@0: * the operation will fail with U_IDNA_STD3_ASCII_RULES_ERROR michael@0: * michael@0: * @param status ICU error code in/out parameter. michael@0: * Must fulfill U_SUCCESS before the function call. michael@0: * @return <0 or 0 or >0 as usual for string comparisons michael@0: * @stable ICU 2.6 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: uidna_compare( const UChar *s1, int32_t length1, michael@0: const UChar *s2, int32_t length2, michael@0: int32_t options, michael@0: UErrorCode* status); michael@0: michael@0: #endif /* #if !UCONFIG_NO_IDNA */ michael@0: michael@0: #endif