lib/silcutil/silcmime.h

   1 /*
   2
   3   silcmime.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2005 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 /****h* silcutil/SILC MIME Interface
  21  *
  22  * DESCRIPTION
  23  *
  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.
  27  *
  28  ***/
  29
  30 #ifndef SILCMIME_H
  31 #define SILCMIME_H
  32
  33 /****s* silcutil/SILCMIMEAPI/SilcMime
  34  *
  35  * NAME
  36  *
  37  *    typedef struct SilcMimeStruct *SilcMime;
  38  *
  39  * DESCRIPTION
  40  *
  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.
  44  *
  45  ***/
  46 typedef struct SilcMimeStruct *SilcMime;
  47
  48 /****s* silcutil/SILCMIMEAPI/SilcMimeAssembler
  49  *
  50  * NAME
  51  *
  52  *    typedef struct SilcMimeAssemblerStruct *SilcMimeAssembler;
  53  *
  54  * DESCRIPTION
  55  *
  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.
  59  *
  60  ***/
  61 typedef struct SilcMimeAssemblerStruct *SilcMimeAssembler;
  62
  63 /****f* silcutil/SILCMIMEAPI/silc_mime_alloc
  64  *
  65  * SYNOPSIS
  66  *
  67  *    SilcMime silc_mime_alloc(void)
  68  *
  69  * DESCRIPTION
  70  *
  71  *    Allocates SILC Mime message context.
  72  *
  73  ***/
  74 SilcMime silc_mime_alloc(void);
  75
  76 /****f* silcutil/SILCMIMEAPI/silc_mime_free
  77  *
  78  * SYNOPSIS
  79  *
  80  *    void silc_mime_alloc(SilcMime mime)
  81  *
  82  * DESCRIPTION
  83  *
  84  *    Frees `mime' context.
  85  *
  86  ***/
  87 void silc_mime_free(SilcMime mime);
  88
  89 /****f* silcutil/SILCMIMEAPI/silc_mime_assembler_alloc
  90  *
  91  * SYNOPSIS
  92  *
  93  *    SilcMimeAssembler silc_mime_assembler_alloc(void);
  94  *
  95  * DESCRIPTION
  96  *
  97  *    Allocates MIME fragment assembler.
  98  *
  99  ***/
 100 SilcMimeAssembler silc_mime_assembler_alloc(void);
 101
 102 /****f* silcutil/SILCMIMEAPI/silc_mime_assembler_free
 103  *
 104  * SYNOPSIS
 105  *
 106  *    void silc_mime_assembler_free(SilcMimeAssembler assembler)
 107  *
 108  * DESCRIPTION
 109  *
 110  *    Frees `assembler' context.
 111  *
 112  ***/
 113 void silc_mime_assembler_free(SilcMimeAssembler assembler);
 114
 115 /****f* silcutil/SILCMIMEAPI/silc_mime_decode
 116  *
 117  * SYNOPSIS
 118  *
 119  *    SilcMime silc_mime_decode(const unsigned char *data,
 120  *                              SilcUInt32 data_len);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    Decodes a MIME message and returns the parsed message into newly
 125  *    allocated SilcMime context.
 126  *
 127  * EXAMPLE
 128  *
 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");
 132  *    ...
 133  *
 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);
 138  *
 139  ***/
 140 SilcMime silc_mime_decode(const unsigned char *data, SilcUInt32 data_len);
 141
 142 /****f* silcutil/SILCMIMEAPI/silc_mime_encode
 143  *
 144  * SYNOPSIS
 145  *
 146  *    unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
 147  *
 148  * DESCRIPTION
 149  *
 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
 153  *    as well.
 154  *
 155  *    If you want to create fragmented MIME message use the function
 156  *    silc_mime_encode_partial.
 157  *
 158  ***/
 159 unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
 160
 161 /****f* silcutil/SILCMIMEAPI/silc_mime_assemble
 162  *
 163  * SYNOPSIS
 164  *
 165  *    SilcMime silc_mime_assemble(SilcMimeAssembler assembler,
 166  *                                SilcMime partial);
 167  *
 168  * DESCRIPTION
 169  *
 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'.
 176  *
 177  * EXAMPLE
 178  *
 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)
 184  *        return;
 185  *      ...
 186  *    }
 187  *
 188  ***/
 189 SilcMime silc_mime_assemble(SilcMimeAssembler assembler, SilcMime partial);
 190
 191 /****f* silcutil/SILCMIMEAPI/silc_mime_encode_partial
 192  *
 193  * SYNOPSIS
 194  *
 195  *    SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
 196  *
 197  * DESCRIPTION
 198  *
 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.
 204  *
 205  *    To assemble the fragments into a complete MIME message the
 206  *    silc_mime_assemble can be used.
 207  *
 208  ***/
 209 SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
 210
 211 /****f* silcutil/SILCMIMEAPI/silc_mime_partial_free
 212  *
 213  * SYNOPSIS
 214  *
 215  *    void silc_mime_partial_free(SilcDList partials);
 216  *
 217  * DESCRIPTION
 218  *
 219  *    This function must be called to free the list returned by the
 220  *    silc_mime_encode_partial function.
 221  *
 222  ***/
 223 void silc_mime_partial_free(SilcDList partials);
 224
 225 /****f* silcutil/SILCMIMEAPI/silc_mime_add_field
 226  *
 227  * SYNOPSIS
 228  *
 229  *    void silc_mime_add_field(SilcMime mime,
 230  *                             const char *field, const char *value);
 231  *
 232  * DESCRIPTION
 233  *
 234  *    Adds a field indicated by `field' to MIME message `mime'.  The field
 235  *    value is `value'.
 236  *
 237  * EXAMPLE
 238  *
 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");
 242  *
 243  ***/
 244 void silc_mime_add_field(SilcMime mime, const char *field, const char *value);
 245
 246 /****f* silcutil/SILCMIMEAPI/silc_mime_get_field
 247  *
 248  * SYNOPSIS
 249  *
 250  *    const char *silc_mime_get_field(SilcMime mime, const char *field);
 251  *
 252  * DESCRIPTION
 253  *
 254  *    Returns the `field' value or NULL if such field does not exist in the
 255  *    MIME message `mime'.
 256  *
 257  ***/
 258 const char *silc_mime_get_field(SilcMime mime, const char *field);
 259
 260 /****f* silcutil/SILCMIMEAPI/silc_mime_add_data
 261  *
 262  * SYNOPSIS
 263  *
 264  *    void silc_mime_add_data(SilcMime mime, const unsigned char *data,
 265  *                            SilcUInt32 data_len);
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Adds the actual MIME data to the `mime' message.
 270  *
 271  ***/
 272 void silc_mime_add_data(SilcMime mime, const unsigned char *data,
 273                         SilcUInt32 data_len);
 274
 275 /****f* silcutil/SILCMIMEAPI/silc_mime_get_data
 276  *
 277  * SYNOPSIS
 278  *
 279  *    const unsigned char *
 280  *    silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
 281  *
 282  * DESCRIPTION
 283  *
 284  *    Returns the MIME data from the `mime' message.
 285  *
 286  ***/
 287 const unsigned char *silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
 288
 289 /****f* silcutil/SILCMIMEAPI/silc_mime_is_partial
 290  *
 291  * SYNOPSIS
 292  *
 293  *    SilcBool silc_mime_is_partial(SilcMime mime);
 294  *
 295  * DESCRIPTION
 296  *
 297  *    Returns TRUE if the MIME message `mime' is a partial MIME fragment.
 298  *
 299  ***/
 300 SilcBool silc_mime_is_partial(SilcMime mime);
 301
 302 /****f* silcutil/SILCMIMEAPI/silc_mime_set_multipart
 303  *
 304  * SYNOPSIS
 305  *
 306  *    void silc_mime_set_multipart(SilcMime mime, const char *type,
 307  *                                 const char *boundary);
 308  *
 309  * DESCRIPTION
 310  *
 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.
 314  *
 315  ***/
 316 void silc_mime_set_multipart(SilcMime mime, const char *type,
 317                              const char *boundary);
 318
 319 /****f* silcutil/SILCMIMEAPI/silc_mime_add_multipart
 320  *
 321  * SYNOPSIS
 322  *
 323  *    SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
 324  *
 325  * DESCRIPTION
 326  *
 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.
 331  *
 332  * NOTES
 333  *
 334  *    The silc_mime_set_multipart must be called for `mime' before parts
 335  *    can be added to it.  Otherwise FALSE will be returned.
 336  *
 337  * EXAMPLE
 338  *
 339  *    part = silc_mime_alloc();
 340  *    silc_mime_add_field(part, "Content-Type", "image/jpeg");
 341  *    silc_mime_add_data(part, data, data_len);
 342  *
 343  *    silc_mime_set_multipart(mime, "mixed", "boundary1");
 344  *    silc_mime_add_multipart(mime, part);
 345  *
 346  ***/
 347 SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
 348
 349 /****f* silcutil/SILCMIMEAPI/silc_mime_is_multipart
 350  *
 351  * SYNOPSIS
 352  *
 353  *    SilcBool silc_mime_is_multipart(SilcMime mime);
 354  *
 355  * DESCRIPTION
 356  *
 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.
 359  *
 360  ***/
 361 SilcBool silc_mime_is_multipart(SilcMime mime);
 362
 363 /****f* silcutil/SILCMIMEAPI/silc_mime_get_multiparts
 364  *
 365  * SYNOPSIS
 366  *
 367  *    SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
 368  *
 369  * DESCRIPTION
 370  *
 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.
 376  *
 377  ***/
 378 SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
 379
 380 #endif /* SILCMIME_H */