libidn: punycode.h Source File

libidn 1.33

punycode.h
Go to the documentation of this file.
1 /* punycode.h --- Declarations for punycode functions.
2 Copyright (C) 2002-2016 Simon Josefsson
3
4 This file is part of GNU Libidn.
5
6 GNU Libidn is free software: you can redistribute it and/or
7 modify it under the terms of either:
8
9 * the GNU Lesser General Public License as published by the Free
10 Software Foundation; either version 3 of the License, or (at
11 your option) any later version.
12
13 or
14
15 * the GNU General Public License as published by the Free
16 Software Foundation; either version 2 of the License, or (at
17 your option) any later version.
18
19 or both in parallel, as here.
20
21 GNU Libidn is distributed in the hope that it will be useful,
22 but WITHOUT ANY WARRANTY; without even the implied warranty of
23 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24 General Public License for more details.
25
26 You should have received copies of the GNU General Public License and
27 the GNU Lesser General Public License along with this program. If
28 not, see <http://www.gnu.org/licenses/>. */
29
30 /*
31 * This file is derived from RFC 3492bis written by Adam M. Costello,
32 * downloaded from http://www.nicemice.net/idn/punycode-spec.gz on
33 * 2015-03-02 with SHA1 a966a8017f6be579d74a50a226accc7607c40133, a
34 * copy of which is stored in the GNU Libidn version controlled
35 * repository under doc/specification/punycode-spec.gz.
36 *
37 * The changes compared to Adam's file include: re-indentation, adding
38 * the license boilerplate and this comment, adding the #ifndef
39 * PUNYCODE_H and IDNAPI blocks, changing the return code of
40 * punycode_encode and punycode_decode from enum to int, simplifying
41 * the definition of punycode_uint by #include'ing idn-int.h and using
42 * uint32_t instead of limit.h-based code, adding Punycode_status and
43 * punycode_strerror, adding 'extern IDNAPI' declarations to function
44 * prototypes, and mentioning variable names in function prototypes.
45 *
46 * Adam's file contains the following:
47 *
48 * punycode-sample.c 2.0.0 (2004-Mar-21-Sun)
49 * http://www.nicemice.net/idn/
50 * Adam M. Costello
51 * http://www.nicemice.net/amc/
52 *
53 * This is ANSI C code (C89) implementing Punycode 1.0.x.
54 *
55 * Disclaimer and license: Regarding this entire document or any
56 * portion of it (including the pseudocode and C code), the author
57 * makes no guarantees and is not responsible for any damage resulting
58 * from its use. The author grants irrevocable permission to anyone
59 * to use, modify, and distribute it in any way that does not diminish
60 * the rights of anyone else to use, modify, and distribute it,
61 * provided that redistributed derivative works do not contain
62 * misleading author or version information. Derivative works need
63 * not be licensed under similar terms.
64 */
65
66 #ifndef PUNYCODE_H
67 # define PUNYCODE_H
68
69 # ifndef IDNAPI
70 # if defined LIBIDN_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
71 # define IDNAPI __attribute__((__visibility__("default")))
72 # elif defined LIBIDN_BUILDING && defined _MSC_VER && ! defined LIBIDN_STATIC
73 # define IDNAPI __declspec(dllexport)
74 # elif defined _MSC_VER && ! defined LIBIDN_STATIC
75 # define IDNAPI __declspec(dllimport)
76 # else
77 # define IDNAPI
78 # endif
79 # endif
80
81 #ifdef __cplusplus
82 extern "C"
83 {
84 #endif
85
86 /************************************************************/
87 /* Public interface (would normally go in its own .h file): */
88
89 #include <stddef.h> /* size_t */
90 #include <idn-int.h> /* uint32_t */
91
92 enum punycode_status
93 {
94 punycode_success = 0,
95 punycode_bad_input = 1, /* Input is invalid. */
96 punycode_big_output = 2, /* Output would exceed the space provided. */
97 punycode_overflow = 3 /* Wider integers needed to process input. */
98 };
99
100 typedef enum
101 {
102 PUNYCODE_SUCCESS = punycode_success,
103 PUNYCODE_BAD_INPUT = punycode_bad_input,
104 PUNYCODE_BIG_OUTPUT = punycode_big_output,
105 PUNYCODE_OVERFLOW = punycode_overflow
106 } Punycode_status;
107
108 extern IDNAPI const char *punycode_strerror (Punycode_status rc);
109
110 /* punycode_uint needs to be unsigned and needs to be */
111 /* at least 26 bits wide. The particular type can be */
112 /* specified by defining PUNYCODE_UINT, otherwise a */
113 /* suitable type will be chosen automatically. */
114
115 typedef uint32_t punycode_uint;
116
117 extern IDNAPI int punycode_encode (size_t input_length,
118 const punycode_uint input[],
119 const unsigned char case_flags[],
120 size_t * output_length, char output[]);
121
122 /*
123 punycode_encode() converts a sequence of code points (presumed to be
124 Unicode code points) to Punycode.
125
126 Input arguments (to be supplied by the caller):
127
128 input_length
129 The number of code points in the input array and the number
130 of flags in the case_flags array.
131
132 input
133 An array of code points. They are presumed to be Unicode
134 code points, but that is not strictly necessary. The
135 array contains code points, not code units. UTF-16 uses
136 code units D800 through DFFF to refer to code points
137 10000..10FFFF. The code points D800..DFFF do not occur in
138 any valid Unicode string. The code points that can occur in
139 Unicode strings (0..D7FF and E000..10FFFF) are also called
140 Unicode scalar values.
141
142 case_flags
143 A null pointer or an array of boolean values parallel to
144 the input array. Nonzero (true, flagged) suggests that the
145 corresponding Unicode character be forced to uppercase after
146 being decoded (if possible), and zero (false, unflagged)
147 suggests that it be forced to lowercase (if possible).
148 ASCII code points (0..7F) are encoded literally, except that
149 ASCII letters are forced to uppercase or lowercase according
150 to the corresponding case flags. If case_flags is a null
151 pointer then ASCII letters are left as they are, and other
152 code points are treated as unflagged.
153
154 Output arguments (to be filled in by the function):
155
156 output
157 An array of ASCII code points. It is *not* null-terminated;
158 it will contain zeros if and only if the input contains
159 zeros. (Of course the caller can leave room for a
160 terminator and add one if needed.)
161
162 Input/output arguments (to be supplied by the caller and overwritten
163 by the function):
164
165 output_length
166 The caller passes in the maximum number of ASCII code points
167 that it can receive. On successful return it will contain
168 the number of ASCII code points actually output.
169
170 Return value:
171
172 Can be any of the punycode_status values defined above except
173 punycode_bad_input. If not punycode_success, then output_size
174 and output might contain garbage.
175 */
176
177 extern IDNAPI int punycode_decode (size_t input_length,
178 const char input[],
179 size_t * output_length,
180 punycode_uint output[],
181 unsigned char case_flags[]);
182
183 /*
184 punycode_decode() converts Punycode to a sequence of code points
185 (presumed to be Unicode code points).
186
187 Input arguments (to be supplied by the caller):
188
189 input_length
190 The number of ASCII code points in the input array.
191
192 input
193 An array of ASCII code points (0..7F).
194
195 Output arguments (to be filled in by the function):
196
197 output
198 An array of code points like the input argument of
199 punycode_encode() (see above).
200
201 case_flags
202 A null pointer (if the flags are not needed by the caller)
203 or an array of boolean values parallel to the output array.
204 Nonzero (true, flagged) suggests that the corresponding
205 Unicode character be forced to uppercase by the caller (if
206 possible), and zero (false, unflagged) suggests that it
207 be forced to lowercase (if possible). ASCII code points
208 (0..7F) are output already in the proper case, but their
209 flags will be set appropriately so that applying the flags
210 would be harmless.
211
212 Input/output arguments (to be supplied by the caller and overwritten
213 by the function):
214
215 output_length
216 The caller passes in the maximum number of code points
217 that it can receive into the output array (which is also
218 the maximum number of flags that it can receive into the
219 case_flags array, if case_flags is not a null pointer). On
220 successful return it will contain the number of code points
221 actually output (which is also the number of flags actually
222 output, if case_flags is not a null pointer). The decoder
223 will never need to output more code points than the number
224 of ASCII code points in the input, because of the way the
225 encoding is defined. The number of code points output
226 cannot exceed the maximum possible value of a punycode_uint,
227 even if the supplied output_length is greater than that.
228
229 Return value:
230
231 Can be any of the punycode_status values defined above. If not
232 punycode_success, then output_length, output, and case_flags
233 might contain garbage.
234 */
235
236 #ifdef __cplusplus
237 }
238 #endif
239 #endif /* PUNYCODE_H */
punycode_encode
IDNAPI int punycode_encode(size_t input_length, const punycode_uint input[], const unsigned char case_flags[], size_t *output_length, char output[])
Definition: punycode.c:196
punycode_big_output
Definition: punycode.h:96
punycode_decode
IDNAPI int punycode_decode(size_t input_length, const char input[], size_t *output_length, punycode_uint output[], unsigned char case_flags[])
Definition: punycode.c:345
punycode_overflow
Definition: punycode.h:97
punycode_success
Definition: punycode.h:94
PUNYCODE_SUCCESS
Definition: punycode.h:102
PUNYCODE_OVERFLOW
Definition: punycode.h:105
punycode_status
punycode_status
Definition: punycode.h:92
PUNYCODE_BIG_OUTPUT
Definition: punycode.h:104
IDNAPI
#define IDNAPI
Definition: punycode.h:77
punycode_strerror
IDNAPI const char * punycode_strerror(Punycode_status rc)
Definition: strerror-punycode.c:57
punycode_bad_input
Definition: punycode.h:95
PUNYCODE_BAD_INPUT
Definition: punycode.h:103
Punycode_status
Punycode_status
Definition: punycode.h:100
punycode_uint
uint32_t punycode_uint
Definition: punycode.h:115