5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2002 - 2003 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 String Utilities
24 * String manipulation utility routines. These routines provides
25 * various helper functions for encoding, decoding and otherwise
33 /****f* silcutil/SilcStrUtilAPI/silc_pem_encode
37 * char *silc_pem_encode(unsigned char *data, SilcUInt32 len);
41 * Encodes data into PEM encoding. Returns NULL terminated PEM encoded
42 * data string. Note: This is originally public domain code and is
46 char *silc_pem_encode(unsigned char *data, SilcUInt32 len);
48 /****f* silcutil/SilcStrUtilAPI/silc_pem_encode_file
52 * char *silc_pem_encode_file(unsigned char *data, SilcUInt32 data_len);
56 * Same as silc_pem_encode() but puts newline ('\n') every 72 characters.
59 char *silc_pem_encode_file(unsigned char *data, SilcUInt32 data_len);
61 /****f* silcutil/SilcStrUtilAPI/silc_pem_decode
65 * unsigned char *silc_pem_decode(unsigned char *pem, SilcUInt32 pem_len,
66 * SilcUInt32 *ret_len);
70 * Decodes PEM into data. Returns the decoded data. Note: This is
71 * originally public domain code and is still PD.
74 unsigned char *silc_pem_decode(unsigned char *pem, SilcUInt32 pem_len,
77 /****d* silcutil/SilcStrUtilAPI/SilcStringEncoding
81 * typedef enum { ... } SilcStringEncoding;
85 * String encoding definitions used with the UTF-8 encoding and
86 * decoding functions. By default, systems should use SILC_STRING_LANGUAGE
87 * since it encodes and decodes correctly according to local system
88 * language and character set.
93 SILC_STRING_ASCII = 0, /* Any 8 bit ASCII encoding (default) */
94 SILC_STRING_ASCII_ESC = 1, /* 7 bit ASCII (>0x7f escaped) */
95 SILC_STRING_BMP = 2, /* 16 bit, UCS-2, BMP, ISO/IEC 10646 */
96 SILC_STRING_BMP_LSB = 3, /* BMP, least significant byte first */
97 SILC_STRING_UNIVERSAL = 4, /* 32 bit, UCS-4, Universal, ISO/IEC 10646 */
98 SILC_STRING_UNIVERSAL_LSB = 5, /* Universal, least significant byte first */
99 SILC_STRING_LANGUAGE = 6, /* Language and charset specific conversion
100 on those platforms that support iconv().
101 Fallback is SILC_STRING_ASCII. */
102 } SilcStringEncoding;
105 /****f* silcutil/SilcStrUtilAPI/silc_utf8_encode
109 * SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
110 * SilcStringEncoding bin_encoding,
111 * unsigned char *utf8, SilcUInt32 utf8_size);
115 * Encodes the string `bin' of which encoding is `bin_encoding' to the
116 * UTF-8 encoding into the buffer `utf8' which is of size of `utf8_size'.
117 * Returns the length of the UTF-8 encoded string, or zero (0) on error.
118 * By default `bin_encoding' is ASCII, and the caller needs to know the
119 * encoding of the input string if it is anything else.
122 SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
123 SilcStringEncoding bin_encoding,
124 unsigned char *utf8, SilcUInt32 utf8_size);
126 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decode
130 * SilcUInt32 silc_utf8_decode(const unsigned char *utf8,
131 * SilcUInt32 utf8_len,
132 * SilcStringEncoding bin_encoding,
133 * unsigned char *bin, SilcUInt32 bin_size);
137 * Decodes UTF-8 encoded string `utf8' to string of which encoding is
138 * to be `bin_encoding', into the `bin' buffer of size of `bin_size'.
139 * Returns the length of the decoded buffer, or zero (0) on error.
140 * By default `bin_encoding' is ASCII, and the caller needs to know to
141 * which encoding the output string is to be encoded if ASCII is not
145 SilcUInt32 silc_utf8_decode(const unsigned char *utf8, SilcUInt32 utf8_len,
146 SilcStringEncoding bin_encoding,
147 unsigned char *bin, SilcUInt32 bin_size);
149 /****f* silcutil/SilcStrUtilAPI/silc_utf8_encoded_len
153 * SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin,
154 * SilcUInt32 bin_len,
155 * SilcStringEncoding bin_encoding);
159 * Returns the length of UTF-8 encoded string if the `bin' of
160 * encoding of `bin_encoding' is encoded with silc_utf8_encode.
163 SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, SilcUInt32 bin_len,
164 SilcStringEncoding bin_encoding);
166 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decoded_len
170 * SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin,
171 * SilcUInt32 bin_len,
172 * SilcStringEncoding bin_encoding);
176 * Returns the length of decoded string if the `bin' of encoding of
177 * `bin_encoding' is decoded with silc_utf8_decode.
180 SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin, SilcUInt32 bin_len,
181 SilcStringEncoding bin_encoding);
183 /****f* silcutil/SilcStrUtilAPI/silc_utf8_valid
187 * bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
191 * Returns TRUE if the `utf8' string of length of `utf8_len' is valid
192 * UTF-8 encoded string, FALSE if it is not UTF-8 encoded string.
195 bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
197 /****f* silcutil/SilcStrUtilAPI/silc_mime_parse
202 * silc_mime_parse(const unsigned char *mime, SilcUInt32 mime_len,
203 * char *version, SilcUInt32 version_size,
204 * char *content_type, SilcUInt32 content_type_size,
205 * char *transfer_encoding,
206 * SilcUInt32 transfer_encoding_size,
207 * unsigned char **mime_data_ptr,
208 * SilcUInt32 *mime_data_len);
212 * Parses MIME header indicated by `mime' data block of length of
213 * `mime_len'. Returns TRUE if the `mime' is valid MIME object.
214 * Parses from the MIME header the MIME Version (if present) and
215 * copies it to the `version' pointer if provided, content type
216 * indicating the data in the MIME object and copies it to the
217 * `content_type' if provided, and the tranfer encoding (if present)
218 * indicating the encoding of the data and copies it to the
219 * `content_transfer_encoding' if provided.
221 * The pointer to the actual data in the MIME object is saved into
222 * `mime_data_ptr'. The pointer is a location in the `mime' and it
223 * does not allocate or copy anything, ie. the `mime_data_ptr' is a
224 * pointer to the `mime'. The `mime_data_len' indicates the length of
225 * the data without the MIME header. The caller is responsible of
226 * NULL terminating the buffers it provides.
230 silc_mime_parse(const unsigned char *mime, SilcUInt32 mime_len,
231 char *version, SilcUInt32 version_size,
232 char *content_type, SilcUInt32 content_type_size,
233 char *transfer_encoding, SilcUInt32 transfer_encoding_size,
234 unsigned char **mime_data_ptr, SilcUInt32 *mime_data_len);
236 /****f* silcutil/SilcStrUtilAPI/silc_strncat
240 * char *silc_strncat(char *dest, SilcUInt32 dest_size,
241 * const char *src, SilcUInt32 src_len);
245 * Concatenates the `src' into `dest'. If `src_len' is more than the
246 * size of the `dest' (minus NULL at the end) the `src' will be
250 char *silc_strncat(char *dest, SilcUInt32 dest_size,
251 const char *src, SilcUInt32 src_len);
253 #endif /* SILCSTRUTIL_H */