libidn 1.43

punycode.h
Go to the documentation of this file.
1/* punycode.h --- Declarations for punycode functions.
2 Copyright (C) 2002-2025 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 <https://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
77# ifndef IDNAPI
78# if defined LIBIDN_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
79# define IDNAPI __attribute__((__visibility__("default")))
80# elif defined LIBIDN_BUILDING && defined _MSC_VER && ! defined LIBIDN_STATIC
81# define IDNAPI __declspec(dllexport)
82# elif defined _MSC_VER && ! defined LIBIDN_STATIC
83# define IDNAPI __declspec(dllimport)
84# else
85# define IDNAPI
86# endif
87# endif
88
89# ifdef __cplusplus
90 extern "C"
91{
92# endif
93
94/************************************************************/
95/* Public interface (would normally go in its own .h file): */
96
97# include <stddef.h> /* size_t */
98# include <idn-int.h> /* uint32_t */
99
100 enum punycode_status
101 {
102 punycode_success = 0,
103 punycode_bad_input = 1, /* Input is invalid. */
104 punycode_big_output = 2, /* Output would exceed the space provided. */
105 punycode_overflow = 3 /* Wider integers needed to process input. */
106 };
107
108 typedef enum
109 {
110 PUNYCODE_SUCCESS = punycode_success,
111 PUNYCODE_BAD_INPUT = punycode_bad_input,
112 PUNYCODE_BIG_OUTPUT = punycode_big_output,
113 PUNYCODE_OVERFLOW = punycode_overflow
114 } Punycode_status;
115
116 extern IDNAPI const char *punycode_strerror (Punycode_status rc);
117
118/* punycode_uint needs to be unsigned and needs to be */
119/* at least 26 bits wide. The particular type can be */
120/* specified by defining PUNYCODE_UINT, otherwise a */
121/* suitable type will be chosen automatically. */
122
123 typedef uint32_t punycode_uint;
124
125 extern IDNAPI int punycode_encode (size_t input_length,
126 const punycode_uint input[],
127 const unsigned char case_flags[],
128 size_t *output_length, char output[]);
129
130/*
131 punycode_encode() converts a sequence of code points (presumed to be
132 Unicode code points) to Punycode.
133
134 Input arguments (to be supplied by the caller):
135
136 input_length
137 The number of code points in the input array and the number
138 of flags in the case_flags array.
139
140 input
141 An array of code points. They are presumed to be Unicode
142 code points, but that is not strictly necessary. The
143 array contains code points, not code units. UTF-16 uses
144 code units D800 through DFFF to refer to code points
145 10000..10FFFF. The code points D800..DFFF do not occur in
146 any valid Unicode string. The code points that can occur in
147 Unicode strings (0..D7FF and E000..10FFFF) are also called
148 Unicode scalar values.
149
150 case_flags
151 A null pointer or an array of boolean values parallel to
152 the input array. Nonzero (true, flagged) suggests that the
153 corresponding Unicode character be forced to uppercase after
154 being decoded (if possible), and zero (false, unflagged)
155 suggests that it be forced to lowercase (if possible).
156 ASCII code points (0..7F) are encoded literally, except that
157 ASCII letters are forced to uppercase or lowercase according
158 to the corresponding case flags. If case_flags is a null
159 pointer then ASCII letters are left as they are, and other
160 code points are treated as unflagged.
161
162 Output arguments (to be filled in by the function):
163
164 output
165 An array of ASCII code points. It is *not* null-terminated;
166 it will contain zeros if and only if the input contains
167 zeros. (Of course the caller can leave room for a
168 terminator and add one if needed.)
169
170 Input/output arguments (to be supplied by the caller and overwritten
171 by the function):
172
173 output_length
174 The caller passes in the maximum number of ASCII code points
175 that it can receive. On successful return it will contain
176 the number of ASCII code points actually output.
177
178 Return value:
179
180 Can be any of the punycode_status values defined above except
181 punycode_bad_input. If not punycode_success, then output_size
182 and output might contain garbage.
183*/
184
185 extern IDNAPI int punycode_decode (size_t input_length,
186 const char input[],
187 size_t *output_length,
188 punycode_uint output[],
189 unsigned char case_flags[]);
190
191/*
192 punycode_decode() converts Punycode to a sequence of code points
193 (presumed to be Unicode code points).
194
195 Input arguments (to be supplied by the caller):
196
197 input_length
198 The number of ASCII code points in the input array.
199
200 input
201 An array of ASCII code points (0..7F).
202
203 Output arguments (to be filled in by the function):
204
205 output
206 An array of code points like the input argument of
207 punycode_encode() (see above).
208
209 case_flags
210 A null pointer (if the flags are not needed by the caller)
211 or an array of boolean values parallel to the output array.
212 Nonzero (true, flagged) suggests that the corresponding
213 Unicode character be forced to uppercase by the caller (if
214 possible), and zero (false, unflagged) suggests that it
215 be forced to lowercase (if possible). ASCII code points
216 (0..7F) are output already in the proper case, but their
217 flags will be set appropriately so that applying the flags
218 would be harmless.
219
220 Input/output arguments (to be supplied by the caller and overwritten
221 by the function):
222
223 output_length
224 The caller passes in the maximum number of code points
225 that it can receive into the output array (which is also
226 the maximum number of flags that it can receive into the
227 case_flags array, if case_flags is not a null pointer). On
228 successful return it will contain the number of code points
229 actually output (which is also the number of flags actually
230 output, if case_flags is not a null pointer). The decoder
231 will never need to output more code points than the number
232 of ASCII code points in the input, because of the way the
233 encoding is defined. The number of code points output
234 cannot exceed the maximum possible value of a punycode_uint,
235 even if the supplied output_length is greater than that.
236
237 Return value:
238
239 Can be any of the punycode_status values defined above. If not
240 punycode_success, then output_length, output, and case_flags
241 might contain garbage.
242*/
243
244# ifdef __cplusplus
245}
246# endif
247#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_strerror
IDNAPI const char * punycode_strerror(Punycode_status rc)
Definition strerror-punycode.c:57
punycode_status
punycode_status
Definition punycode.h:101
punycode_bad_input
@ punycode_bad_input
Definition punycode.h:103
punycode_success
@ punycode_success
Definition punycode.h:102
punycode_overflow
@ punycode_overflow
Definition punycode.h:105
punycode_big_output
@ punycode_big_output
Definition punycode.h:104
Punycode_status
Punycode_status
Definition punycode.h:109
PUNYCODE_OVERFLOW
@ PUNYCODE_OVERFLOW
Definition punycode.h:113
PUNYCODE_SUCCESS
@ PUNYCODE_SUCCESS
Definition punycode.h:110
PUNYCODE_BAD_INPUT
@ PUNYCODE_BAD_INPUT
Definition punycode.h:111
PUNYCODE_BIG_OUTPUT
@ PUNYCODE_BIG_OUTPUT
Definition punycode.h:112
IDNAPI
#define IDNAPI
Definition punycode.h:85
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:348
punycode_uint
uint32_t punycode_uint
Definition punycode.h:123