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