Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/uidna.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
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