5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 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 MIME Interface
24 * Simple implementation of MIME. Supports creation and parsing of simple
25 * MIME messages, multipart MIME messages, including nested multiparts, and
26 * MIME fragmentation and defragmentation.
33 /****s* silcutil/SILCMIMEAPI/SilcMime
37 * typedef struct SilcMimeStruct *SilcMime;
41 * This context is the actual MIME message and is allocated
42 * by silc_mime_alloc and given as argument to all silc_mime_*
43 * functions. It is freed by the silc_mime_free function.
46 typedef struct SilcMimeStruct *SilcMime;
48 /****s* silcutil/SILCMIMEAPI/SilcMimeAssembler
52 * typedef struct SilcMimeAssemblerStruct *SilcMimeAssembler;
56 * This context is a SILC MIME Assembler that is used to assemble partial
57 * MIME messages (fgraments) into complete MIME messages. It is allocated
58 * by silc_mime_assembler_alloc and freed by silc_mime_assembler_free.
61 typedef struct SilcMimeAssemblerStruct *SilcMimeAssembler;
63 /****f* silcutil/SILCMIMEAPI/silc_mime_alloc
67 * SilcMime silc_mime_alloc(void)
71 * Allocates SILC Mime message context.
74 SilcMime silc_mime_alloc(void);
76 /****f* silcutil/SILCMIMEAPI/silc_mime_free
80 * void silc_mime_alloc(SilcMime mime)
84 * Frees `mime' context.
87 void silc_mime_free(SilcMime mime);
89 /****f* silcutil/SILCMIMEAPI/silc_mime_assembler_alloc
93 * SilcMimeAssembler silc_mime_assembler_alloc(void);
97 * Allocates MIME fragment assembler.
100 SilcMimeAssembler silc_mime_assembler_alloc(void);
102 /****f* silcutil/SILCMIMEAPI/silc_mime_assembler_free
106 * void silc_mime_assembler_free(SilcMimeAssembler assembler)
110 * Frees `assembler' context.
113 void silc_mime_assembler_free(SilcMimeAssembler assembler);
115 /****f* silcutil/SILCMIMEAPI/silc_mime_decode
119 * SilcMime silc_mime_decode(const unsigned char *data,
120 * SilcUInt32 data_len);
124 * Decodes a MIME message and returns the parsed message into newly
125 * allocated SilcMime context.
129 * // Parse MIME message and get its content type
130 * mime = silc_mime_decode(data, data_len);
131 * type = silc_mime_get_field(mime, "Content-Type");
134 * // Assemble received MIME fragment
135 * mime = silc_mime_decode(data, data_len);
136 * if (silc_mime_is_partial(mime) == TRUE)
137 * silc_mime_assmeble(assembler, mime);
140 SilcMime silc_mime_decode(const unsigned char *data, SilcUInt32 data_len);
142 /****f* silcutil/SILCMIMEAPI/silc_mime_encode
146 * unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
150 * Encodes the `mime' context into a raw MIME message (may be human
151 * readable). The caller must free the returned buffer. If the `mime'
152 * is multipart MIME message all parts will be automatically encoded
155 * If you want to create fragmented MIME message use the function
156 * silc_mime_encode_partial.
159 unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
161 /****f* silcutil/SILCMIMEAPI/silc_mime_assemble
165 * SilcMime silc_mime_assemble(SilcMimeAssembler assembler,
170 * Processes and attempts to assemble the received MIME fragment `partial'.
171 * To check if a received MIME message is a fragment use the
172 * silc_mime_is_partial function. Returns NULL if all fragments has not
173 * yet been received, or the newly allocated completed MIME message if
174 * all fragments were received. The caller must free the returned
175 * SilcMime context. The caller must not free the `partial'.
179 * // Assemble received MIME fragment
180 * mime = silc_mime_decode(data, data_len);
181 * if (silc_mime_is_partial(mime) == TRUE) {
182 * complete = silc_mime_assmeble(assembler, mime);
183 * if (complete == NULL)
189 SilcMime silc_mime_assemble(SilcMimeAssembler assembler, SilcMime partial);
191 /****f* silcutil/SILCMIMEAPI/silc_mime_encode_partial
195 * SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
199 * Same as silc_mime_encode except fragments the MIME message `mime'
200 * if it is larger than `max_size' in bytes. Returns the MIME fragments
201 * in SilcDList where each entry is SilcBuffer context. The caller must
202 * free the returned list and all SilcBuffer entries in it by calling
203 * silc_mime_partial_free function.
205 * To assemble the fragments into a complete MIME message the
206 * silc_mime_assemble can be used.
209 SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
211 /****f* silcutil/SILCMIMEAPI/silc_mime_partial_free
215 * void silc_mime_partial_free(SilcDList partials);
219 * This function must be called to free the list returned by the
220 * silc_mime_encode_partial function.
223 void silc_mime_partial_free(SilcDList partials);
225 /****f* silcutil/SILCMIMEAPI/silc_mime_add_field
229 * void silc_mime_add_field(SilcMime mime,
230 * const char *field, const char *value);
234 * Adds a field indicated by `field' to MIME message `mime'. The field
239 * silc_mime_add_field(mime, "MIME-Version", "1.0");
240 * silc_mime_add_field(mime, "Content-Type", "image/jpeg");
241 * silc_mime_add_field(mime, "Content-Transfer-Encoding", "binary");
244 void silc_mime_add_field(SilcMime mime, const char *field, const char *value);
246 /****f* silcutil/SILCMIMEAPI/silc_mime_get_field
250 * const char *silc_mime_get_field(SilcMime mime, const char *field);
254 * Returns the `field' value or NULL if such field does not exist in the
255 * MIME message `mime'.
258 const char *silc_mime_get_field(SilcMime mime, const char *field);
260 /****f* silcutil/SILCMIMEAPI/silc_mime_add_data
264 * void silc_mime_add_data(SilcMime mime, const unsigned char *data,
265 * SilcUInt32 data_len);
269 * Adds the actual MIME data to the `mime' message.
272 void silc_mime_add_data(SilcMime mime, const unsigned char *data,
273 SilcUInt32 data_len);
275 /****f* silcutil/SILCMIMEAPI/silc_mime_get_data
279 * const unsigned char *
280 * silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
284 * Returns the MIME data from the `mime' message.
287 const unsigned char *silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
289 /****f* silcutil/SILCMIMEAPI/silc_mime_is_partial
293 * SilcBool silc_mime_is_partial(SilcMime mime);
297 * Returns TRUE if the MIME message `mime' is a partial MIME fragment.
300 SilcBool silc_mime_is_partial(SilcMime mime);
302 /****f* silcutil/SILCMIMEAPI/silc_mime_set_multipart
306 * void silc_mime_set_multipart(SilcMime mime, const char *type,
307 * const char *boundary);
311 * Sets the `mime' to be a multipart MIME message. The `type' specifies
312 * the multipart type, usually "mixed", but can be something else too.
313 * The `boundary' specifies the multipart boundary.
316 void silc_mime_set_multipart(SilcMime mime, const char *type,
317 const char *boundary);
319 /****f* silcutil/SILCMIMEAPI/silc_mime_add_multipart
323 * SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
327 * Adds a multipart `part` to MIME message `mime'. The `part' will be
328 * freed automatically when silc_mime_free is called for `mime'. Returns
329 * TRUE if `part' was added to `mime' and FALSE if `mime' is not marked
330 * as multipart MIME message.
334 * The silc_mime_set_multipart must be called for `mime' before parts
335 * can be added to it. Otherwise FALSE will be returned.
339 * part = silc_mime_alloc();
340 * silc_mime_add_field(part, "Content-Type", "image/jpeg");
341 * silc_mime_add_data(part, data, data_len);
343 * silc_mime_set_multipart(mime, "mixed", "boundary1");
344 * silc_mime_add_multipart(mime, part);
347 SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
349 /****f* silcutil/SILCMIMEAPI/silc_mime_is_multipart
353 * SilcBool silc_mime_is_multipart(SilcMime mime);
357 * Returns TRUE if the MIME message `mime' is a multipart MIME message.
358 * Its parts can be get by calling silc_mime_get_multiparts.
361 SilcBool silc_mime_is_multipart(SilcMime mime);
363 /****f* silcutil/SILCMIMEAPI/silc_mime_get_multiparts
367 * SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
371 * Returns list of the parts from the MIME message `mime'. Each entry
372 * in the list is SilcMime context. The caller must not free the returned
373 * list or the SilcMime contexts in the list. Returns NULL if no parts
374 * exists in the MIME message. Returns the multipart type (like "mixed")
375 * into `type' pointer.
378 SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
380 #endif /* SILCMIME_H */