libidn  1.31
punycode.h
Go to the documentation of this file.
1 /* punycode.h --- Declarations for punycode functions.
2  Copyright (C) 2002-2015 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 
93  {
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  {
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 */
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
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_status
Definition: punycode.h:92
#define IDNAPI
Definition: punycode.h:77
IDNAPI const char * punycode_strerror(Punycode_status rc)
Punycode_status
Definition: punycode.h:100
uint32_t punycode_uint
Definition: punycode.h:115