SILC Runtime Toolkit 1.2 Beta 1

[runtime.git] / lib / silcutil / silcmime.h

diff --git a/lib/silcutil/silcmime.h b/lib/silcutil/silcmime.h
index 653a662527441626f3a110efbd2fa663cd218279..e2831e6a4620098fdf5b22f0bfc06821cabb65c7 100644 (file)
--- a/lib/silcutil/silcmime.h
+++ b/lib/silcutil/silcmime.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2005 - 2006 Pekka Riikonen
+  Copyright (C) 2005 - 2008 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
@@ -17,20 +17,23 @@
 
 */
 
-/****h* silcutil/SILC MIME Interface
+/****h* silcutil/MIME Interface
  *
  * DESCRIPTION
  *
- * Simple implementation of MIME.  Supports creation and parsing of simple
+ * Simple MIME Interface.  This API supports creation and parsing of simple
  * MIME messages, multipart MIME messages, including nested multiparts, and
  * MIME fragmentation and defragmentation.
  *
+ * SILC Mime API is not thread-safe.  If the same SilcMime context must be
+ * used in multithreaded environment concurrency control must be employed.
+ *
  ***/
 
 #ifndef SILCMIME_H
 #define SILCMIME_H
 
-/****s* silcutil/SILCMIMEAPI/SilcMime
+/****s* silcutil/SilcMime
  *
  * NAME
  *
@@ -45,7 +48,7 @@
  ***/
 typedef struct SilcMimeStruct *SilcMime;
 
-/****s* silcutil/SILCMIMEAPI/SilcMimeAssembler
+/****s* silcutil/SilcMimeAssembler
  *
  * NAME
  *
@@ -60,7 +63,7 @@ typedef struct SilcMimeStruct *SilcMime;
  ***/
 typedef struct SilcMimeAssemblerStruct *SilcMimeAssembler;
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_alloc
+/****f* silcutil/silc_mime_alloc
  *
  * SYNOPSIS
  *
@@ -68,12 +71,13 @@ 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);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_free
+/****f* silcutil/silc_mime_free
  *
  * SYNOPSIS
  *
@@ -86,7 +90,7 @@ SilcMime silc_mime_alloc(void);
  ***/
 void silc_mime_free(SilcMime mime);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_assembler_alloc
+/****f* silcutil/silc_mime_assembler_alloc
  *
  * SYNOPSIS
  *
@@ -94,12 +98,13 @@ 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);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_assembler_free
+/****f* silcutil/silc_mime_assembler_free
  *
  * SYNOPSIS
  *
@@ -112,7 +117,30 @@ SilcMimeAssembler silc_mime_assembler_alloc(void);
  ***/
 void silc_mime_assembler_free(SilcMimeAssembler assembler);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_decode
+/****f* silcutil/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/silc_mime_decode
  *
  * SYNOPSIS
  *
@@ -143,7 +171,7 @@ void silc_mime_assembler_free(SilcMimeAssembler assembler);
 SilcMime silc_mime_decode(SilcMime mime, const unsigned char *data,
                          SilcUInt32 data_len);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_encode
+/****f* silcutil/silc_mime_encode
  *
  * SYNOPSIS
  *
@@ -162,7 +190,7 @@ SilcMime silc_mime_decode(SilcMime mime, const unsigned char *data,
  ***/
 unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_assemble
+/****f* silcutil/silc_mime_assemble
  *
  * SYNOPSIS
  *
@@ -173,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'.
@@ -192,7 +220,7 @@ unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
  ***/
 SilcMime silc_mime_assemble(SilcMimeAssembler assembler, SilcMime partial);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_encode_partial
+/****f* silcutil/silc_mime_encode_partial
  *
  * SYNOPSIS
  *
@@ -212,7 +240,7 @@ SilcMime silc_mime_assemble(SilcMimeAssembler assembler, SilcMime partial);
  ***/
 SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_partial_free
+/****f* silcutil/silc_mime_partial_free
  *
  * SYNOPSIS
  *
@@ -226,7 +254,7 @@ SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
  ***/
 void silc_mime_partial_free(SilcDList partials);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_add_field
+/****f* silcutil/silc_mime_add_field
  *
  * SYNOPSIS
  *
@@ -247,7 +275,7 @@ void silc_mime_partial_free(SilcDList partials);
  ***/
 void silc_mime_add_field(SilcMime mime, const char *field, const char *value);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_get_field
+/****f* silcutil/silc_mime_get_field
  *
  * SYNOPSIS
  *
@@ -261,7 +289,7 @@ void silc_mime_add_field(SilcMime mime, const char *field, const char *value);
  ***/
 const char *silc_mime_get_field(SilcMime mime, const char *field);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_add_data
+/****f* silcutil/silc_mime_add_data
  *
  * SYNOPSIS
  *
@@ -276,7 +304,7 @@ const char *silc_mime_get_field(SilcMime mime, const char *field);
 void silc_mime_add_data(SilcMime mime, const unsigned char *data,
                        SilcUInt32 data_len);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_get_data
+/****f* silcutil/silc_mime_get_data
  *
  * SYNOPSIS
  *
@@ -290,7 +318,7 @@ 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
+/****f* silcutil/silc_mime_steal_data
  *
  * SYNOPSIS
  *
@@ -306,7 +334,7 @@ const unsigned char *silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
  ***/
 unsigned char *silc_mime_steal_data(SilcMime mime, SilcUInt32 *data_len);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_is_partial
+/****f* silcutil/silc_mime_is_partial
  *
  * SYNOPSIS
  *
@@ -319,7 +347,7 @@ unsigned char *silc_mime_steal_data(SilcMime mime, SilcUInt32 *data_len);
  ***/
 SilcBool silc_mime_is_partial(SilcMime mime);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_set_multipart
+/****f* silcutil/silc_mime_set_multipart
  *
  * SYNOPSIS
  *
@@ -336,7 +364,7 @@ SilcBool silc_mime_is_partial(SilcMime mime);
 void silc_mime_set_multipart(SilcMime mime, const char *type,
                             const char *boundary);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_add_multipart
+/****f* silcutil/silc_mime_add_multipart
  *
  * SYNOPSIS
  *
@@ -366,7 +394,7 @@ void silc_mime_set_multipart(SilcMime mime, const char *type,
  ***/
 SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_is_multipart
+/****f* silcutil/silc_mime_is_multipart
  *
  * SYNOPSIS
  *
@@ -380,7 +408,7 @@ SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
  ***/
 SilcBool silc_mime_is_multipart(SilcMime mime);
 
-/****f* silcutil/SILCMIMEAPI/silc_mime_get_multiparts
+/****f* silcutil/silc_mime_get_multiparts
  *
  * SYNOPSIS
  *