5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2004 - 2005 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC Stringprep
24 * Interface for the stringprep (RFC3454) standard, that is used to prepare
25 * strings for internationalization. The interface can be used to prepare
26 * strings according to various stringprep profiles. The profiles defines
27 * what characters the strings may contain, what characters are prohibited
28 * and how the strings are prepared.
32 #ifndef SILCSTRINGPREP_H
33 #define SILCSTRINGPREP_H
35 /****d* silcutil/SilcStringprep/SilcStringprepStatus
39 * typedef enum { ... } SilcStringprepStatus;
43 * Status and errors returned by silc_stringprep.
48 SILC_STRINGPREP_OK, /* Preparation success */
49 SILC_STRINGPREP_ERR_UNASSIGNED, /* Contains unassigned characters */
50 SILC_STRINGPREP_ERR_PROHIBITED, /* Contains prohibited characters */
51 SILC_STRINGPREP_ERR_BIDI_PROHIBITED, /* BIDI contains prohibited chars */
52 SILC_STRINGPREP_ERR_BIDI_RAL_WITH_L, /* BIDI has both R/AL and L */
53 SILC_STRINGPREP_ERR_BIDI_RAL, /* BIDI has R/AL but not as leading
54 and/or trailing character. */
55 SILC_STRINGPREP_ERR_OUT_OF_MEMORY, /* System out of memory */
56 SILC_STRINGPREP_ERR_ENCODING, /* Character encoding error */
57 SILC_STRINGPREP_ERR_UNSUP_ENCODING, /* Unsupported character encoding */
58 SILC_STRINGPREP_ERR_UNSUP_PROFILE, /* Unsupported profile */
59 SILC_STRINGPREP_ERR, /* Unknown error */
60 } SilcStringprepStatus;
63 /****d* silcutil/SilcStringprep/SilcStringprepFlags
67 * typedef enum { ... } SilcStringprepFlags;
71 * Flags that change how the strings are prepared with silc_stringprep.
76 SILC_STRINGPREP_NONE = 0x00, /* No flags */
77 SILC_STRINGPREP_ALLOW_UNASSIGNED = 0x01, /* Allow unassigned characters
78 without returning error. */
79 } SilcStringprepFlags;
83 #define SILC_IDENTIFIER_PREP "silc-identifier-prep"
84 #define SILC_IDENTIFIERC_PREP "silc-identifierc-prep"
85 #define SILC_IDENTIFIER_CH_PREP "silc-identifier-ch-prep"
86 #define SILC_CASEFOLD_PREP "silc-casefold-prep"
88 /****f* silcutil/SilcStringprep/silc_stringprep
92 * SilcStringprepStatus
93 * silc_stringprep(const unsigned char *bin, SilcUInt32 bin_len,
94 * SilcStringEncoding bin_encoding,
95 * const char *profile_name,
96 * SilcStringprepFlags flags,
97 * unsigned char **out, SilcUInt32 *out_len,
98 * SilcStringEncoding out_encoding);
102 * Prepares the input string 'bin' of length 'bin_len' of encoding
103 * 'bin_encoding' according to the stringrep profile 'profile_name'.
104 * Returns the prepared and allocated string into 'out'. The 'out_len'
105 * indicates the length of the prepared string. This returns the
106 * SilcStringprepStatus which indicates the status of the preparation.
107 * For example, if the input string contains prohibited characters
108 * (according to the used profile) this function will return error.
109 * The 'flags' however can be used to modify the behavior of this
110 * function. Caller must free the returned 'out' string.
112 * The output string will be encoded into the character encoding
113 * defined by the 'out_encoding'. This allows caller to have for
114 * example the input string as locale specific string and output string
115 * as UTF-8 encoded string.
117 * If the 'out' is NULL this function merely performs the preparation
118 * process, but does not return anything. In this case this function
119 * could be used to for example verify that an input string that ought
120 * to have been prepared correctly was done so.
122 * Available profile names:
124 * SILC_IDENTIFIER_PREP Prepares SILC identifier strings
125 * SILC_IDENTIFIER_CH_PREP Prepares SILC channel name strings
126 * SILC_IDENTIFIERC_PREP Casefolds identifier strings
127 * SILC_CASEFOLD_PREP Casefolding and normalizing
131 silc_stringprep(const unsigned char *bin, SilcUInt32 bin_len,
132 SilcStringEncoding bin_encoding,
133 const char *profile_name,
134 SilcStringprepFlags flags,
135 unsigned char **out, SilcUInt32 *out_len,
136 SilcStringEncoding out_encoding);
138 #endif /* SILCSTRINGPREP_H */