libidn: stringprep.h Source File

libidn 1.44

stringprep.h
Go to the documentation of this file.
1/* stringprep.h --- Header file for stringprep functions.
2 Copyright (C) 2002-2026 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#ifndef STRINGPREP_H
31# define STRINGPREP_H
32
40
41# ifndef IDNAPI
42# if defined LIBIDN_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
43# define IDNAPI __attribute__((__visibility__("default")))
44# elif defined LIBIDN_BUILDING && defined _MSC_VER && ! defined LIBIDN_STATIC
45# define IDNAPI __declspec(dllexport)
46# elif defined _MSC_VER && ! defined LIBIDN_STATIC
47# define IDNAPI __declspec(dllimport)
48# else
49# define IDNAPI
50# endif
51# endif
52
53# include <stddef.h> /* size_t */
54# include <sys/types.h> /* ssize_t */
55# include <idn-int.h> /* uint32_t */
56
57# ifdef __cplusplus
58extern "C"
59{
60# endif
61
62# define STRINGPREP_VERSION "1.44"
63
64/* Error codes. */
65 typedef enum
66 {
67 STRINGPREP_OK = 0,
68 /* Stringprep errors. */
69 STRINGPREP_CONTAINS_UNASSIGNED = 1,
70 STRINGPREP_CONTAINS_PROHIBITED = 2,
71 STRINGPREP_BIDI_BOTH_L_AND_RAL = 3,
72 STRINGPREP_BIDI_LEADTRAIL_NOT_RAL = 4,
73 STRINGPREP_BIDI_CONTAINS_PROHIBITED = 5,
74 /* Error in calling application. */
75 STRINGPREP_TOO_SMALL_BUFFER = 100,
76 STRINGPREP_PROFILE_ERROR = 101,
77 STRINGPREP_FLAG_ERROR = 102,
78 STRINGPREP_UNKNOWN_PROFILE = 103,
79 STRINGPREP_ICONV_ERROR = 104,
80 /* Internal errors. */
81 STRINGPREP_NFKC_FAILED = 200,
82 STRINGPREP_MALLOC_ERROR = 201
83 } Stringprep_rc;
84
85/* Flags used when calling stringprep(). */
86 typedef enum
87 {
88 STRINGPREP_NO_NFKC = 1,
89 STRINGPREP_NO_BIDI = 2,
90 STRINGPREP_NO_UNASSIGNED = 4
91 } Stringprep_profile_flags;
92
93/* Steps in a stringprep profile. */
94 typedef enum
95 {
96 STRINGPREP_NFKC = 1,
97 STRINGPREP_BIDI = 2,
98 STRINGPREP_MAP_TABLE = 3,
99 STRINGPREP_UNASSIGNED_TABLE = 4,
100 STRINGPREP_PROHIBIT_TABLE = 5,
101 STRINGPREP_BIDI_PROHIBIT_TABLE = 6,
102 STRINGPREP_BIDI_RAL_TABLE = 7,
103 STRINGPREP_BIDI_L_TABLE = 8
104 } Stringprep_profile_steps;
105
106# define STRINGPREP_MAX_MAP_CHARS 4
107
108 /* *INDENT-OFF* */
109
110 /* Why INDENT-OFF? GTK-DOC has a bug
111 * <https://gitlab.gnome.org/GNOME/gtk-doc/-/issues/37> which causes
112 * parsing of structs to fail unless the terminating } is at the
113 * beginning of the line. We hard-code the header file to be like
114 * that, and add the INDENT-OFF markers so that indent won't restore
115 * them. When that bug is fixed, remove the INDENT-* marker, run
116 * 'make indent', and make sure that
117 * doc/reference/libidn-decl-list.txt stay the same.
118 *
119 * Of course, exposing these struct's in the public header file in
120 * the first place was a mistake.
121 */
122
131 struct Stringprep_table_element
132 {
133 uint32_t start;
134 uint32_t end;
135 uint32_t map[STRINGPREP_MAX_MAP_CHARS];
136};
137 typedef struct Stringprep_table_element Stringprep_table_element;
138
148 struct Stringprep_table
149 {
150 Stringprep_profile_steps operation;
151 Stringprep_profile_flags flags;
152 const Stringprep_table_element *table;
153 size_t table_size;
154};
155
160 typedef struct Stringprep_table Stringprep_profile;
161
169 struct Stringprep_profiles
170 {
171 const char *name;
172 const Stringprep_profile *tables;
173};
174 typedef struct Stringprep_profiles Stringprep_profiles;
175 /* *INDENT-ON* */
176
177 extern IDNAPI const Stringprep_profiles stringprep_profiles[];
178
179/* Profiles */
180 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_A_1[];
181 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_B_1[];
182 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_B_2[];
183 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_B_3[];
184 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_1_1[];
185 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_1_2[];
186 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_2_1[];
187 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_2_2[];
188 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_3[];
189 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_4[];
190 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_5[];
191 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_6[];
192 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_7[];
193 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_8[];
194 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_C_9[];
195 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_D_1[];
196 extern IDNAPI const Stringprep_table_element stringprep_rfc3454_D_2[];
197
198 /* Nameprep */
199
200 extern IDNAPI const Stringprep_profile stringprep_nameprep[];
201
202# define stringprep_nameprep(in, maxlen) \
203 stringprep(in, maxlen, 0, stringprep_nameprep)
204
205# define stringprep_nameprep_no_unassigned(in, maxlen) \
206 stringprep(in, maxlen, STRINGPREP_NO_UNASSIGNED, stringprep_nameprep)
207
208 /* SASL */
209
210 extern IDNAPI const Stringprep_profile stringprep_saslprep[];
211 extern IDNAPI const Stringprep_table_element
212 stringprep_saslprep_space_map[];
213 extern IDNAPI const Stringprep_profile stringprep_plain[];
214 extern IDNAPI const Stringprep_profile stringprep_trace[];
215
216# define stringprep_plain(in, maxlen) \
217 stringprep(in, maxlen, 0, stringprep_plain)
218
219 /* Kerberos */
220
221 extern IDNAPI const Stringprep_profile stringprep_kerberos5[];
222
223# define stringprep_kerberos5(in, maxlen) \
224 stringprep(in, maxlen, 0, stringprep_kerberos5)
225
226 /* XMPP */
227
228 extern IDNAPI const Stringprep_profile stringprep_xmpp_nodeprep[];
229 extern IDNAPI const Stringprep_profile stringprep_xmpp_resourceprep[];
230 extern IDNAPI const Stringprep_table_element
231 stringprep_xmpp_nodeprep_prohibit[];
232
233# define stringprep_xmpp_nodeprep(in, maxlen) \
234 stringprep(in, maxlen, 0, stringprep_xmpp_nodeprep)
235# define stringprep_xmpp_resourceprep(in, maxlen) \
236 stringprep(in, maxlen, 0, stringprep_xmpp_resourceprep)
237
238 /* iSCSI */
239
240 extern IDNAPI const Stringprep_profile stringprep_iscsi[];
241 extern IDNAPI const Stringprep_table_element stringprep_iscsi_prohibit[];
242
243# define stringprep_iscsi(in, maxlen) \
244 stringprep(in, maxlen, 0, stringprep_iscsi)
245
246 /* API */
247
248 extern IDNAPI int stringprep_4i (uint32_t * ucs4, size_t *len,
249 size_t maxucs4len,
250 Stringprep_profile_flags flags,
251 const Stringprep_profile * profile);
252 extern IDNAPI int stringprep_4zi (uint32_t * ucs4, size_t maxucs4len,
253 Stringprep_profile_flags flags,
254 const Stringprep_profile * profile);
255 extern IDNAPI int stringprep (char *in, size_t maxlen,
256 Stringprep_profile_flags flags,
257 const Stringprep_profile * profile);
258
259 extern IDNAPI int stringprep_profile (const char *in,
260 char **out,
261 const char *profile,
262 Stringprep_profile_flags flags);
263
264 extern IDNAPI const char *stringprep_strerror (Stringprep_rc rc);
265
266 extern IDNAPI const char *stringprep_check_version (const char
267 *req_version);
268
269/* Utility */
270
271 extern IDNAPI int stringprep_unichar_to_utf8 (uint32_t c, char *outbuf);
272 extern IDNAPI uint32_t stringprep_utf8_to_unichar (const char *p);
273
274 extern IDNAPI uint32_t *stringprep_utf8_to_ucs4 (const char *str,
275 ssize_t len,
276 size_t *items_written);
277 extern IDNAPI char *stringprep_ucs4_to_utf8 (const uint32_t * str,
278 ssize_t len,
279 size_t *items_read,
280 size_t *items_written);
281
282 extern IDNAPI char *stringprep_utf8_nfkc_normalize (const char *str,
283 ssize_t len);
284 extern IDNAPI uint32_t *stringprep_ucs4_nfkc_normalize (const uint32_t *
285 str, ssize_t len);
286
287 extern IDNAPI const char *stringprep_locale_charset (void);
288 extern IDNAPI char *stringprep_convert (const char *str,
289 const char *to_codeset,
290 const char *from_codeset);
291 extern IDNAPI char *stringprep_locale_to_utf8 (const char *str);
292 extern IDNAPI char *stringprep_utf8_to_locale (const char *str);
293
294# ifdef __cplusplus
295}
296# endif
297
298#endif /* STRINGPREP_H */
IDNAPI
#define IDNAPI
Definition idn-free.h:49
stringprep_xmpp_nodeprep_prohibit
const Stringprep_table_element stringprep_xmpp_nodeprep_prohibit[]
Definition profiles.c:97
stringprep_saslprep
const Stringprep_profile stringprep_saslprep[]
Definition profiles.c:243
stringprep_profiles
const Stringprep_profiles stringprep_profiles[]
Definition profiles.c:34
stringprep_trace
const Stringprep_profile stringprep_trace[]
Definition profiles.c:171
stringprep_iscsi_prohibit
const Stringprep_table_element stringprep_iscsi_prohibit[]
Definition profiles.c:187
stringprep_saslprep_space_map
const Stringprep_table_element stringprep_saslprep_space_map[]
Definition profiles.c:222
stringprep_rfc3454_B_2
const Stringprep_table_element stringprep_rfc3454_B_2[]
Definition rfc3454.c:456
stringprep_rfc3454_C_6
const Stringprep_table_element stringprep_rfc3454_C_6[]
Definition rfc3454.c:3763
stringprep_rfc3454_D_1
const Stringprep_table_element stringprep_rfc3454_D_1[]
Definition rfc3454.c:3846
stringprep_rfc3454_C_4
const Stringprep_table_element stringprep_rfc3454_C_4[]
Definition rfc3454.c:3723
stringprep_rfc3454_C_2_1
const Stringprep_table_element stringprep_rfc3454_C_2_1[]
Definition rfc3454.c:3609
stringprep_rfc3454_C_8
const Stringprep_table_element stringprep_rfc3454_C_8[]
Definition rfc3454.c:3791
stringprep_rfc3454_C_2_2
const Stringprep_table_element stringprep_rfc3454_C_2_2[]
Definition rfc3454.c:3682
stringprep_rfc3454_C_9
const Stringprep_table_element stringprep_rfc3454_C_9[]
Definition rfc3454.c:3834
stringprep_rfc3454_B_3
const Stringprep_table_element stringprep_rfc3454_B_3[]
Definition rfc3454.c:2484
stringprep_rfc3454_C_7
const Stringprep_table_element stringprep_rfc3454_C_7[]
Definition rfc3454.c:3778
stringprep_rfc3454_C_3
const Stringprep_table_element stringprep_rfc3454_C_3[]
Definition rfc3454.c:3709
stringprep_rfc3454_C_1_1
const Stringprep_table_element stringprep_rfc3454_C_1_1[]
Definition rfc3454.c:3473
stringprep_rfc3454_A_1
const Stringprep_table_element stringprep_rfc3454_A_1[]
Definition rfc3454.c:13
stringprep_rfc3454_C_1_2
const Stringprep_table_element stringprep_rfc3454_C_1_2[]
Definition rfc3454.c:3524
stringprep_rfc3454_C_5
const Stringprep_table_element stringprep_rfc3454_C_5[]
Definition rfc3454.c:3752
stringprep_rfc3454_B_1
const Stringprep_table_element stringprep_rfc3454_B_1[]
Definition rfc3454.c:419
stringprep_rfc3454_D_2
const Stringprep_table_element stringprep_rfc3454_D_2[]
Definition rfc3454.c:3890
stringprep_xmpp_resourceprep
#define stringprep_xmpp_resourceprep(in, maxlen)
Definition stringprep.h:235
stringprep_profile
IDNAPI int stringprep_profile(const char *in, char **out, const char *profile, Stringprep_profile_flags flags)
Definition stringprep.c:493
Stringprep_profile
struct Stringprep_table Stringprep_profile
Definition stringprep.h:160
stringprep_ucs4_nfkc_normalize
IDNAPI uint32_t * stringprep_ucs4_nfkc_normalize(const uint32_t *str, ssize_t len)
Definition nfkc.c:1076
stringprep_xmpp_nodeprep
#define stringprep_xmpp_nodeprep(in, maxlen)
Definition stringprep.h:233
Stringprep_profile_steps
Stringprep_profile_steps
Definition stringprep.h:95
STRINGPREP_BIDI_PROHIBIT_TABLE
@ STRINGPREP_BIDI_PROHIBIT_TABLE
Definition stringprep.h:101
STRINGPREP_BIDI_RAL_TABLE
@ STRINGPREP_BIDI_RAL_TABLE
Definition stringprep.h:102
STRINGPREP_NFKC
@ STRINGPREP_NFKC
Definition stringprep.h:96
STRINGPREP_PROHIBIT_TABLE
@ STRINGPREP_PROHIBIT_TABLE
Definition stringprep.h:100
STRINGPREP_UNASSIGNED_TABLE
@ STRINGPREP_UNASSIGNED_TABLE
Definition stringprep.h:99
STRINGPREP_BIDI
@ STRINGPREP_BIDI
Definition stringprep.h:97
STRINGPREP_MAP_TABLE
@ STRINGPREP_MAP_TABLE
Definition stringprep.h:98
STRINGPREP_BIDI_L_TABLE
@ STRINGPREP_BIDI_L_TABLE
Definition stringprep.h:103
stringprep_kerberos5
#define stringprep_kerberos5(in, maxlen)
Definition stringprep.h:223
stringprep_unichar_to_utf8
IDNAPI int stringprep_unichar_to_utf8(uint32_t c, char *outbuf)
Definition nfkc.c:962
Stringprep_profile_flags
Stringprep_profile_flags
Definition stringprep.h:87
STRINGPREP_NO_BIDI
@ STRINGPREP_NO_BIDI
Definition stringprep.h:89
STRINGPREP_NO_NFKC
@ STRINGPREP_NO_NFKC
Definition stringprep.h:88
STRINGPREP_NO_UNASSIGNED
@ STRINGPREP_NO_UNASSIGNED
Definition stringprep.h:90
stringprep_utf8_to_unichar
IDNAPI uint32_t stringprep_utf8_to_unichar(const char *p)
Definition nfkc.c:945
stringprep_plain
#define stringprep_plain(in, maxlen)
Definition stringprep.h:216
stringprep
IDNAPI int stringprep(char *in, size_t maxlen, Stringprep_profile_flags flags, const Stringprep_profile *profile)
Definition stringprep.c:414
Stringprep_rc
Stringprep_rc
Definition stringprep.h:66
STRINGPREP_UNKNOWN_PROFILE
@ STRINGPREP_UNKNOWN_PROFILE
Definition stringprep.h:78
STRINGPREP_NFKC_FAILED
@ STRINGPREP_NFKC_FAILED
Definition stringprep.h:81
STRINGPREP_TOO_SMALL_BUFFER
@ STRINGPREP_TOO_SMALL_BUFFER
Definition stringprep.h:75
STRINGPREP_ICONV_ERROR
@ STRINGPREP_ICONV_ERROR
Definition stringprep.h:79
STRINGPREP_MALLOC_ERROR
@ STRINGPREP_MALLOC_ERROR
Definition stringprep.h:82
STRINGPREP_FLAG_ERROR
@ STRINGPREP_FLAG_ERROR
Definition stringprep.h:77
STRINGPREP_OK
@ STRINGPREP_OK
Definition stringprep.h:67
STRINGPREP_CONTAINS_UNASSIGNED
@ STRINGPREP_CONTAINS_UNASSIGNED
Definition stringprep.h:69
STRINGPREP_CONTAINS_PROHIBITED
@ STRINGPREP_CONTAINS_PROHIBITED
Definition stringprep.h:70
STRINGPREP_BIDI_CONTAINS_PROHIBITED
@ STRINGPREP_BIDI_CONTAINS_PROHIBITED
Definition stringprep.h:73
STRINGPREP_BIDI_BOTH_L_AND_RAL
@ STRINGPREP_BIDI_BOTH_L_AND_RAL
Definition stringprep.h:71
STRINGPREP_BIDI_LEADTRAIL_NOT_RAL
@ STRINGPREP_BIDI_LEADTRAIL_NOT_RAL
Definition stringprep.h:72
STRINGPREP_PROFILE_ERROR
@ STRINGPREP_PROFILE_ERROR
Definition stringprep.h:76
stringprep_utf8_to_ucs4
IDNAPI uint32_t * stringprep_utf8_to_ucs4(const char *str, ssize_t len, size_t *items_written)
Definition nfkc.c:986
stringprep_locale_charset
IDNAPI const char * stringprep_locale_charset(void)
Definition toutf8.c:85
stringprep_utf8_to_locale
IDNAPI char * stringprep_utf8_to_locale(const char *str)
Definition toutf8.c:161
stringprep_4i
IDNAPI int stringprep_4i(uint32_t *ucs4, size_t *len, size_t maxucs4len, Stringprep_profile_flags flags, const Stringprep_profile *profile)
Definition stringprep.c:181
stringprep_nameprep
#define stringprep_nameprep(in, maxlen)
Definition stringprep.h:202
stringprep_utf8_nfkc_normalize
IDNAPI char * stringprep_utf8_nfkc_normalize(const char *str, ssize_t len)
Definition nfkc.c:1048
stringprep_locale_to_utf8
IDNAPI char * stringprep_locale_to_utf8(const char *str)
Definition toutf8.c:145
stringprep_4zi
IDNAPI int stringprep_4zi(uint32_t *ucs4, size_t maxucs4len, Stringprep_profile_flags flags, const Stringprep_profile *profile)
Definition stringprep.c:374
stringprep_strerror
IDNAPI const char * stringprep_strerror(Stringprep_rc rc)
Definition strerror-stringprep.c:78
stringprep_iscsi
#define stringprep_iscsi(in, maxlen)
Definition stringprep.h:243
stringprep_ucs4_to_utf8
IDNAPI char * stringprep_ucs4_to_utf8(const uint32_t *str, ssize_t len, size_t *items_read, size_t *items_written)
Definition nfkc.c:1019
stringprep_check_version
IDNAPI const char * stringprep_check_version(const char *req_version)
Definition version.c:53
stringprep_convert
IDNAPI char * stringprep_convert(const char *str, const char *to_codeset, const char *from_codeset)
Definition toutf8.c:116
STRINGPREP_MAX_MAP_CHARS
#define STRINGPREP_MAX_MAP_CHARS
Definition stringprep.h:106
Stringprep_profiles
Definition stringprep.h:170
Stringprep_profiles::name
const char * name
Definition stringprep.h:171
Stringprep_profiles::tables
const Stringprep_profile * tables
Definition stringprep.h:172
Stringprep_table_element
Definition stringprep.h:132
Stringprep_table_element::end
uint32_t end
Definition stringprep.h:134
Stringprep_table_element::map
uint32_t map[STRINGPREP_MAX_MAP_CHARS]
Definition stringprep.h:135
Stringprep_table_element::start
uint32_t start
Definition stringprep.h:133
Stringprep_table
Definition stringprep.h:149
Stringprep_table::table
const Stringprep_table_element * table
Definition stringprep.h:152
Stringprep_table::flags
Stringprep_profile_flags flags
Definition stringprep.h:151
Stringprep_table::operation
Stringprep_profile_steps operation
Definition stringprep.h:150
Stringprep_table::table_size
size_t table_size
Definition stringprep.h:153