libidn  1.29
punycode.h
Go to the documentation of this file.
1 /* punycode.h --- Declarations for punycode functions.
2  Copyright (C) 2002-2014 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 contains content derived from RFC 3492bis written by Adam
32  * M. Costello.
33  *
34  * Disclaimer and license: Regarding this entire document or any
35  * portion of it (including the pseudocode and C code), the author
36  * makes no guarantees and is not responsible for any damage resulting
37  * from its use. The author grants irrevocable permission to anyone
38  * to use, modify, and distribute it in any way that does not diminish
39  * the rights of anyone else to use, modify, and distribute it,
40  * provided that redistributed derivative works do not contain
41  * misleading author or version information. Derivative works need
42  * not be licensed under similar terms.
43  *
44  * Copyright (C) The Internet Society (2003). All Rights Reserved.
45  *
46  * This document and translations of it may be copied and furnished to
47  * others, and derivative works that comment on or otherwise explain it
48  * or assist in its implementation may be prepared, copied, published
49  * and distributed, in whole or in part, without restriction of any
50  * kind, provided that the above copyright notice and this paragraph are
51  * included on all such copies and derivative works. However, this
52  * document itself may not be modified in any way, such as by removing
53  * the copyright notice or references to the Internet Society or other
54  * Internet organizations, except as needed for the purpose of
55  * developing Internet standards in which case the procedures for
56  * copyrights defined in the Internet Standards process must be
57  * followed, or as required to translate it into languages other than
58  * English.
59  *
60  * The limited permissions granted above are perpetual and will not be
61  * revoked by the Internet Society or its successors or assigns.
62  *
63  * This document and the information contained herein is provided on an
64  * "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
65  * TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
66  * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
67  * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
68  * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
69  */
70 
71 #ifndef PUNYCODE_H
72 # define PUNYCODE_H
73 
74 # ifndef IDNAPI
75 # if defined LIBIDN_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
76 # define IDNAPI __attribute__((__visibility__("default")))
77 # elif defined LIBIDN_BUILDING && defined _MSC_VER && ! defined LIBIDN_STATIC
78 # define IDNAPI __declspec(dllexport)
79 # elif defined _MSC_VER && ! defined LIBIDN_STATIC
80 # define IDNAPI __declspec(dllimport)
81 # else
82 # define IDNAPI
83 # endif
84 # endif
85 
86 #ifdef __cplusplus
87 extern "C"
88 {
89 #endif
90 
91 #include <stddef.h> /* size_t */
92 #include <idn-int.h> /* uint32_t */
93 
95  {
97  punycode_bad_input = 1, /* Input is invalid. */
98  punycode_big_output = 2, /* Output would exceed the space provided. */
99  punycode_overflow = 3 /* Wider integers needed to process input. */
100  };
101 
102  typedef enum
103  {
108  } Punycode_status;
109 
110  extern IDNAPI const char *punycode_strerror (Punycode_status rc);
111 
112 /* punycode_uint needs to be unsigned and needs to be */
113 /* at least 26 bits wide. */
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 REQUIRED. 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 */