Initiate name change for savannah project registration.
[libidn.git] / punycode.h
blob1848f5ae57de8fc8b518750801db08c046b1782b
1 /* punycode.h Declarations for punycode functions.
2 * Copyright (C) 2002 Adam M. Costello
3 * Copyright (C) 2002 Simon Josefsson
5 * This file is part of Libstringprep.
7 * Libstringprep is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * Libstringprep is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with Libstringprep; if not, write to the Free Software
19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 * This file is derived from from draft-ietf-idn-punycode-03.txt by
25 * Adam M. Costello.
27 * Disclaimer and license: Regarding this entire document or any
28 * portion of it (including the pseudocode and C code), the author
29 * makes no guarantees and is not responsible for any damage resulting
30 * from its use. The author grants irrevocable permission to anyone
31 * to use, modify, and distribute it in any way that does not diminish
32 * the rights of anyone else to use, modify, and distribute it,
33 * provided that redistributed derivative works do not contain
34 * misleading author or version information. Derivative works need
35 * not be licensed under similar terms.
39 #ifndef _PUNYCODE_H
40 #define _PUNYCODE_H
42 #ifdef __cplusplus
43 extern "C"
45 #endif
47 enum
49 PUNYCODE_SUCCESS = 0,
50 PUNYCODE_BAD_INPUT, /* Input is invalid. */
51 PUNYCODE_BIG_OUTPUT, /* Output would exceed the space provided. */
52 PUNYCODE_OVERFLOW /* Input needs wider integers to process. */
55 int punycode_encode (size_t input_length,
56 const unsigned long input[],
57 const unsigned char case_flags[],
58 size_t * output_length, char output[]);
60 /* punycode_encode() converts Unicode to Punycode. The input */
61 /* is represented as an array of Unicode code points (not code */
62 /* units; surrogate pairs are not allowed), and the output */
63 /* will be represented as an array of ASCII code points. The */
64 /* output string is *not* null-terminated; it will contain */
65 /* zeros if and only if the input contains zeros. (Of course */
66 /* the caller can leave room for a terminator and add one if */
67 /* needed.) The input_length is the number of code points in */
68 /* the input. The output_length is an in/out argument: the */
69 /* caller passes in the maximum number of code points that it */
70 /* can receive, and on successful return it will contain the */
71 /* number of code points actually output. The case_flags array */
72 /* holds input_length boolean values, where nonzero suggests that */
73 /* the corresponding Unicode character be forced to uppercase */
74 /* after being decoded (if possible), and zero suggests that */
75 /* it be forced to lowercase (if possible). ASCII code points */
76 /* are encoded literally, except that ASCII letters are forced */
77 /* to uppercase or lowercase according to the corresponding */
78 /* uppercase flags. If case_flags is a null pointer then ASCII */
79 /* letters are left as they are, and other code points are */
80 /* treated as if their uppercase flags were zero. The return */
81 /* value can be any of the punycode_status values defined above */
82 /* except punycode_bad_input; if not punycode_success, then */
83 /* output_size and output might contain garbage. */
85 int punycode_decode (size_t input_length,
86 const char input[],
87 size_t * output_length,
88 unsigned long output[], unsigned char case_flags[]);
90 /* punycode_decode() converts Punycode to Unicode. The input is */
91 /* represented as an array of ASCII code points, and the output */
92 /* will be represented as an array of Unicode code points. The */
93 /* input_length is the number of code points in the input. The */
94 /* output_length is an in/out argument: the caller passes in */
95 /* the maximum number of code points that it can receive, and */
96 /* on successful return it will contain the actual number of */
97 /* code points output. The case_flags array needs room for at */
98 /* least output_length values, or it can be a null pointer if the */
99 /* case information is not needed. A nonzero flag suggests that */
100 /* the corresponding Unicode character be forced to uppercase */
101 /* by the caller (if possible), while zero suggests that it be */
102 /* forced to lowercase (if possible). ASCII code points are */
103 /* output already in the proper case, but their flags will be set */
104 /* appropriately so that applying the flags would be harmless. */
105 /* The return value can be any of the punycode_status values */
106 /* defined above; if not punycode_success, then output_length, */
107 /* output, and case_flags might contain garbage. On success, the */
108 /* decoder will never need to write an output_length greater than */
109 /* input_length, because of how the encoding is defined. */
111 #ifdef __cplusplus
113 #endif
114 #endif /* _PUNYCODE_H */