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