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(SilcMime mime, const unsigned char *data,
120 * SilcUInt32 data_len);
124 * Decodes a MIME message and returns the parsed message into newly
125 * allocated SilcMime context and returns it. If `mime' is non-NULL
126 * then the MIME message will be encoded into the pre-allocated `mime'
127 * context and same context is returned. If it is NULL then newly
128 * allocated SilcMime context is returned. On error NULL is returned.
132 * // Parse MIME message and get its content type
133 * mime = silc_mime_decode(NULL, data, data_len);
134 * type = silc_mime_get_field(mime, "Content-Type");
137 * // Assemble received MIME fragment
138 * mime = silc_mime_decode(NULL, data, data_len);
139 * if (silc_mime_is_partial(mime) == TRUE)
140 * silc_mime_assmeble(assembler, mime);
143 SilcMime silc_mime_decode(SilcMime mime, const unsigned char *data,
144 SilcUInt32 data_len);
146 /****f* silcutil/SILCMIMEAPI/silc_mime_encode
150 * unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
154 * Encodes the `mime' context into a raw MIME message (may be human
155 * readable). The caller must free the returned buffer. If the `mime'
156 * is multipart MIME message all parts will be automatically encoded
159 * If you want to create fragmented MIME message use the function
160 * silc_mime_encode_partial.
163 unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
165 /****f* silcutil/SILCMIMEAPI/silc_mime_assemble
169 * SilcMime silc_mime_assemble(SilcMimeAssembler assembler,
174 * Processes and attempts to assemble the received MIME fragment `partial'.
175 * To check if a received MIME message is a fragment use the
176 * silc_mime_is_partial function. Returns NULL if all fragments has not
177 * yet been received, or the newly allocated completed MIME message if
178 * all fragments were received. The caller must free the returned
179 * SilcMime context. The caller must not free the `partial'.
183 * // Assemble received MIME fragment
184 * mime = silc_mime_decode(data, data_len);
185 * if (silc_mime_is_partial(mime) == TRUE) {
186 * complete = silc_mime_assmeble(assembler, mime);
187 * if (complete == NULL)
193 SilcMime silc_mime_assemble(SilcMimeAssembler assembler, SilcMime partial);
195 /****f* silcutil/SILCMIMEAPI/silc_mime_encode_partial
199 * SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
203 * Same as silc_mime_encode except fragments the MIME message `mime'
204 * if it is larger than `max_size' in bytes. Returns the MIME fragments
205 * in SilcDList where each entry is SilcBuffer context. The caller must
206 * free the returned list and all SilcBuffer entries in it by calling
207 * silc_mime_partial_free function.
209 * To assemble the fragments into a complete MIME message the
210 * silc_mime_assemble can be used.
213 SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
215 /****f* silcutil/SILCMIMEAPI/silc_mime_partial_free
219 * void silc_mime_partial_free(SilcDList partials);
223 * This function must be called to free the list returned by the
224 * silc_mime_encode_partial function.
227 void silc_mime_partial_free(SilcDList partials);
229 /****f* silcutil/SILCMIMEAPI/silc_mime_add_field
233 * void silc_mime_add_field(SilcMime mime,
234 * const char *field, const char *value);
238 * Adds a field indicated by `field' to MIME message `mime'. The field
243 * silc_mime_add_field(mime, "MIME-Version", "1.0");
244 * silc_mime_add_field(mime, "Content-Type", "image/jpeg");
245 * silc_mime_add_field(mime, "Content-Transfer-Encoding", "binary");
248 void silc_mime_add_field(SilcMime mime, const char *field, const char *value);
250 /****f* silcutil/SILCMIMEAPI/silc_mime_get_field
254 * const char *silc_mime_get_field(SilcMime mime, const char *field);
258 * Returns the `field' value or NULL if such field does not exist in the
259 * MIME message `mime'.
262 const char *silc_mime_get_field(SilcMime mime, const char *field);
264 /****f* silcutil/SILCMIMEAPI/silc_mime_add_data
268 * void silc_mime_add_data(SilcMime mime, const unsigned char *data,
269 * SilcUInt32 data_len);
273 * Adds the actual MIME data to the `mime' message.
276 void silc_mime_add_data(SilcMime mime, const unsigned char *data,
277 SilcUInt32 data_len);
279 /****f* silcutil/SILCMIMEAPI/silc_mime_get_data
283 * const unsigned char *
284 * silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
288 * Returns the MIME data from the `mime' message.
291 const unsigned char *silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
293 /****f* silcutil/SILCMIMEAPI/silc_mime_is_partial
297 * SilcBool silc_mime_is_partial(SilcMime mime);
301 * Returns TRUE if the MIME message `mime' is a partial MIME fragment.
304 SilcBool silc_mime_is_partial(SilcMime mime);
306 /****f* silcutil/SILCMIMEAPI/silc_mime_set_multipart
310 * void silc_mime_set_multipart(SilcMime mime, const char *type,
311 * const char *boundary);
315 * Sets the `mime' to be a multipart MIME message. The `type' specifies
316 * the multipart type, usually "mixed", but can be something else too.
317 * The `boundary' specifies the multipart boundary.
320 void silc_mime_set_multipart(SilcMime mime, const char *type,
321 const char *boundary);
323 /****f* silcutil/SILCMIMEAPI/silc_mime_add_multipart
327 * SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
331 * Adds a multipart `part` to MIME message `mime'. The `part' will be
332 * freed automatically when silc_mime_free is called for `mime'. Returns
333 * TRUE if `part' was added to `mime' and FALSE if `mime' is not marked
334 * as multipart MIME message.
338 * The silc_mime_set_multipart must be called for `mime' before parts
339 * can be added to it. Otherwise FALSE will be returned.
343 * part = silc_mime_alloc();
344 * silc_mime_add_field(part, "Content-Type", "image/jpeg");
345 * silc_mime_add_data(part, data, data_len);
347 * silc_mime_set_multipart(mime, "mixed", "boundary1");
348 * silc_mime_add_multipart(mime, part);
351 SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
353 /****f* silcutil/SILCMIMEAPI/silc_mime_is_multipart
357 * SilcBool silc_mime_is_multipart(SilcMime mime);
361 * Returns TRUE if the MIME message `mime' is a multipart MIME message.
362 * Its parts can be get by calling silc_mime_get_multiparts.
365 SilcBool silc_mime_is_multipart(SilcMime mime);
367 /****f* silcutil/SILCMIMEAPI/silc_mime_get_multiparts
371 * SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
375 * Returns list of the parts from the MIME message `mime'. Each entry
376 * in the list is SilcMime context. The caller must not free the returned
377 * list or the SilcMime contexts in the list. Returns NULL if no parts
378 * exists in the MIME message. Returns the multipart type (like "mixed")
379 * into `type' pointer.
382 SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
384 #include "silcmime_i.h"
386 #endif /* SILCMIME_H */