X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcmime.h;h=664b526a06adbaaa137947327282a30b437c5edc;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=90684e17986e3f8fe9915d2542d4ec0b3b622bbe;hpb=0f0340b9fbce9704cc7171f8f0104ce9103d2de6;p=silc.git diff --git a/lib/silcutil/silcmime.h b/lib/silcutil/silcmime.h index 90684e17..664b526a 100644 --- a/lib/silcutil/silcmime.h +++ b/lib/silcutil/silcmime.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2005 Pekka Riikonen + Copyright (C) 2005 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -25,6 +25,9 @@ * MIME messages, multipart MIME messages, including nested multiparts, and * MIME fragmentation and defragmentation. * + * SILC Mime API is not thread-safe. If the same MIME context must be + * used in multithreaded environment concurrency control must be employed. + * ***/ #ifndef SILCMIME_H @@ -68,7 +71,8 @@ typedef struct SilcMimeAssemblerStruct *SilcMimeAssembler; * * DESCRIPTION * - * Allocates SILC Mime message context. + * Allocates SILC Mime message context. Returns NULL if system is out of + * memory. * ***/ SilcMime silc_mime_alloc(void); @@ -94,7 +98,8 @@ void silc_mime_free(SilcMime mime); * * DESCRIPTION * - * Allocates MIME fragment assembler. + * Allocates MIME fragment assembler. Returns NULL if system is out of + * memory. * ***/ SilcMimeAssembler silc_mime_assembler_alloc(void); @@ -112,32 +117,59 @@ SilcMimeAssembler silc_mime_assembler_alloc(void); ***/ void silc_mime_assembler_free(SilcMimeAssembler assembler); +/****f* silcutil/SILCMIMEAPI/silc_mime_assembler_purge + * + * SYNOPSIS + * + * void silc_mime_assembler_purge(SilcMimeAssembler assembler, + * SilcUInt32 purge_minutes); + * + * DESCRIPTION + * + * Purges the MIME fragment assembler from old fragments that have never + * completed into a full MIME message. This function may be called + * periodically to purge MIME fragments. The `purge_minutes' specify + * how old fragments are purged. If it is 0, fragments older than 5 minutes + * are purged, by default. The value is in minutes. + * + * It is usefull to call this periodically to assure that memory is not + * consumed needlessly by keeping old unfinished fragments in a long + * running assembler. + * + ***/ +void silc_mime_assembler_purge(SilcMimeAssembler assembler, + SilcUInt32 purge_minutes); + /****f* silcutil/SILCMIMEAPI/silc_mime_decode * * SYNOPSIS * - * SilcMime silc_mime_decode(const unsigned char *data, + * SilcMime silc_mime_decode(SilcMime mime, const unsigned char *data, * SilcUInt32 data_len); * * DESCRIPTION * * Decodes a MIME message and returns the parsed message into newly - * allocated SilcMime context. + * allocated SilcMime context and returns it. If `mime' is non-NULL + * then the MIME message will be encoded into the pre-allocated `mime' + * context and same context is returned. If it is NULL then newly + * allocated SilcMime context is returned. On error NULL is returned. * * EXAMPLE * * // Parse MIME message and get its content type - * mime = silc_mime_decode(data, data_len); + * mime = silc_mime_decode(NULL, data, data_len); * type = silc_mime_get_field(mime, "Content-Type"); * ... * * // Assemble received MIME fragment - * mime = silc_mime_decode(data, data_len); + * mime = silc_mime_decode(NULL, data, data_len); * if (silc_mime_is_partial(mime) == TRUE) * silc_mime_assmeble(assembler, mime); * ***/ -SilcMime silc_mime_decode(const unsigned char *data, SilcUInt32 data_len); +SilcMime silc_mime_decode(SilcMime mime, const unsigned char *data, + SilcUInt32 data_len); /****f* silcutil/SILCMIMEAPI/silc_mime_encode * @@ -169,7 +201,7 @@ unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len); * * Processes and attempts to assemble the received MIME fragment `partial'. * To check if a received MIME message is a fragment use the - * silc_mime_is_partial function. Returns NULL if all fragments has not + * silc_mime_is_partial function. Returns NULL if all fragments have not * yet been received, or the newly allocated completed MIME message if * all fragments were received. The caller must free the returned * SilcMime context. The caller must not free the `partial'. @@ -286,18 +318,34 @@ void silc_mime_add_data(SilcMime mime, const unsigned char *data, ***/ const unsigned char *silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len); +/****f* silcutil/SILCMIMEAPI/silc_mime_steal_data + * + * SYNOPSIS + * + * unsigned char * + * silc_mime_steal_data(SilcMime mime, SilcUInt32 *data_len); + * + * DESCRIPTION + * + * Returns the MIME data from the `mime' message. The data will be + * removed from the `mime' and the caller is responsible of freeing the + * returned pointer. + * + ***/ +unsigned char *silc_mime_steal_data(SilcMime mime, SilcUInt32 *data_len); + /****f* silcutil/SILCMIMEAPI/silc_mime_is_partial * * SYNOPSIS * - * bool silc_mime_is_partial(SilcMime mime); + * SilcBool silc_mime_is_partial(SilcMime mime); * * DESCRIPTION * * Returns TRUE if the MIME message `mime' is a partial MIME fragment. * ***/ -bool silc_mime_is_partial(SilcMime mime); +SilcBool silc_mime_is_partial(SilcMime mime); /****f* silcutil/SILCMIMEAPI/silc_mime_set_multipart * @@ -320,7 +368,7 @@ void silc_mime_set_multipart(SilcMime mime, const char *type, * * SYNOPSIS * - * bool silc_mime_add_multipart(SilcMime mime, SilcMime part); + * SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part); * * DESCRIPTION * @@ -344,13 +392,13 @@ void silc_mime_set_multipart(SilcMime mime, const char *type, * silc_mime_add_multipart(mime, part); * ***/ -bool silc_mime_add_multipart(SilcMime mime, SilcMime part); +SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part); /****f* silcutil/SILCMIMEAPI/silc_mime_is_multipart * * SYNOPSIS * - * bool silc_mime_is_multipart(SilcMime mime); + * SilcBool silc_mime_is_multipart(SilcMime mime); * * DESCRIPTION * @@ -358,7 +406,7 @@ bool silc_mime_add_multipart(SilcMime mime, SilcMime part); * Its parts can be get by calling silc_mime_get_multiparts. * ***/ -bool silc_mime_is_multipart(SilcMime mime); +SilcBool silc_mime_is_multipart(SilcMime mime); /****f* silcutil/SILCMIMEAPI/silc_mime_get_multiparts * @@ -377,4 +425,6 @@ bool silc_mime_is_multipart(SilcMime mime); ***/ SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type); +#include "silcmime_i.h" + #endif /* SILCMIME_H */