libidn  1.41
punycode.h
Go to the documentation of this file.
1 /* punycode.h --- Declarations for punycode functions.
2  Copyright (C) 2002-2022 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 
101  {
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  {
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 */
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_status
Definition: punycode.h:101
@ punycode_bad_input
Definition: punycode.h:103
@ punycode_success
Definition: punycode.h:102
@ punycode_overflow
Definition: punycode.h:105
@ punycode_big_output
Definition: punycode.h:104
Punycode_status
Definition: punycode.h:109
@ PUNYCODE_OVERFLOW
Definition: punycode.h:113
@ PUNYCODE_SUCCESS
Definition: punycode.h:110
@ PUNYCODE_BAD_INPUT
Definition: punycode.h:111
@ PUNYCODE_BIG_OUTPUT
Definition: punycode.h:112
#define IDNAPI
Definition: punycode.h:85
IDNAPI const char * punycode_strerror(Punycode_status rc)
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
uint32_t punycode_uint
Definition: punycode.h:123