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(SilcMime mime, 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 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.
 129  *
 130  * EXAMPLE
 131  *
 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");
 135  *    ...
 136  *
 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);
 141  *
 142  ***/
 143 SilcMime silc_mime_decode(SilcMime mime, const unsigned char *data,
 144                           SilcUInt32 data_len);
 145
 146 /****f* silcutil/SILCMIMEAPI/silc_mime_encode
 147  *
 148  * SYNOPSIS
 149  *
 150  *    unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
 151  *
 152  * DESCRIPTION
 153  *
 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
 157  *    as well.
 158  *
 159  *    If you want to create fragmented MIME message use the function
 160  *    silc_mime_encode_partial.
 161  *
 162  ***/
 163 unsigned char *silc_mime_encode(SilcMime mime, SilcUInt32 *encoded_len);
 164
 165 /****f* silcutil/SILCMIMEAPI/silc_mime_assemble
 166  *
 167  * SYNOPSIS
 168  *
 169  *    SilcMime silc_mime_assemble(SilcMimeAssembler assembler,
 170  *                                SilcMime partial);
 171  *
 172  * DESCRIPTION
 173  *
 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'.
 180  *
 181  * EXAMPLE
 182  *
 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)
 188  *        return;
 189  *      ...
 190  *    }
 191  *
 192  ***/
 193 SilcMime silc_mime_assemble(SilcMimeAssembler assembler, SilcMime partial);
 194
 195 /****f* silcutil/SILCMIMEAPI/silc_mime_encode_partial
 196  *
 197  * SYNOPSIS
 198  *
 199  *    SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
 200  *
 201  * DESCRIPTION
 202  *
 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.
 208  *
 209  *    To assemble the fragments into a complete MIME message the
 210  *    silc_mime_assemble can be used.
 211  *
 212  ***/
 213 SilcDList silc_mime_encode_partial(SilcMime mime, int max_size);
 214
 215 /****f* silcutil/SILCMIMEAPI/silc_mime_partial_free
 216  *
 217  * SYNOPSIS
 218  *
 219  *    void silc_mime_partial_free(SilcDList partials);
 220  *
 221  * DESCRIPTION
 222  *
 223  *    This function must be called to free the list returned by the
 224  *    silc_mime_encode_partial function.
 225  *
 226  ***/
 227 void silc_mime_partial_free(SilcDList partials);
 228
 229 /****f* silcutil/SILCMIMEAPI/silc_mime_add_field
 230  *
 231  * SYNOPSIS
 232  *
 233  *    void silc_mime_add_field(SilcMime mime,
 234  *                             const char *field, const char *value);
 235  *
 236  * DESCRIPTION
 237  *
 238  *    Adds a field indicated by `field' to MIME message `mime'.  The field
 239  *    value is `value'.
 240  *
 241  * EXAMPLE
 242  *
 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");
 246  *
 247  ***/
 248 void silc_mime_add_field(SilcMime mime, const char *field, const char *value);
 249
 250 /****f* silcutil/SILCMIMEAPI/silc_mime_get_field
 251  *
 252  * SYNOPSIS
 253  *
 254  *    const char *silc_mime_get_field(SilcMime mime, const char *field);
 255  *
 256  * DESCRIPTION
 257  *
 258  *    Returns the `field' value or NULL if such field does not exist in the
 259  *    MIME message `mime'.
 260  *
 261  ***/
 262 const char *silc_mime_get_field(SilcMime mime, const char *field);
 263
 264 /****f* silcutil/SILCMIMEAPI/silc_mime_add_data
 265  *
 266  * SYNOPSIS
 267  *
 268  *    void silc_mime_add_data(SilcMime mime, const unsigned char *data,
 269  *                            SilcUInt32 data_len);
 270  *
 271  * DESCRIPTION
 272  *
 273  *    Adds the actual MIME data to the `mime' message.
 274  *
 275  ***/
 276 void silc_mime_add_data(SilcMime mime, const unsigned char *data,
 277                         SilcUInt32 data_len);
 278
 279 /****f* silcutil/SILCMIMEAPI/silc_mime_get_data
 280  *
 281  * SYNOPSIS
 282  *
 283  *    const unsigned char *
 284  *    silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
 285  *
 286  * DESCRIPTION
 287  *
 288  *    Returns the MIME data from the `mime' message.
 289  *
 290  ***/
 291 const unsigned char *silc_mime_get_data(SilcMime mime, SilcUInt32 *data_len);
 292
 293 /****f* silcutil/SILCMIMEAPI/silc_mime_is_partial
 294  *
 295  * SYNOPSIS
 296  *
 297  *    SilcBool silc_mime_is_partial(SilcMime mime);
 298  *
 299  * DESCRIPTION
 300  *
 301  *    Returns TRUE if the MIME message `mime' is a partial MIME fragment.
 302  *
 303  ***/
 304 SilcBool silc_mime_is_partial(SilcMime mime);
 305
 306 /****f* silcutil/SILCMIMEAPI/silc_mime_set_multipart
 307  *
 308  * SYNOPSIS
 309  *
 310  *    void silc_mime_set_multipart(SilcMime mime, const char *type,
 311  *                                 const char *boundary);
 312  *
 313  * DESCRIPTION
 314  *
 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.
 318  *
 319  ***/
 320 void silc_mime_set_multipart(SilcMime mime, const char *type,
 321                              const char *boundary);
 322
 323 /****f* silcutil/SILCMIMEAPI/silc_mime_add_multipart
 324  *
 325  * SYNOPSIS
 326  *
 327  *    SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
 328  *
 329  * DESCRIPTION
 330  *
 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.
 335  *
 336  * NOTES
 337  *
 338  *    The silc_mime_set_multipart must be called for `mime' before parts
 339  *    can be added to it.  Otherwise FALSE will be returned.
 340  *
 341  * EXAMPLE
 342  *
 343  *    part = silc_mime_alloc();
 344  *    silc_mime_add_field(part, "Content-Type", "image/jpeg");
 345  *    silc_mime_add_data(part, data, data_len);
 346  *
 347  *    silc_mime_set_multipart(mime, "mixed", "boundary1");
 348  *    silc_mime_add_multipart(mime, part);
 349  *
 350  ***/
 351 SilcBool silc_mime_add_multipart(SilcMime mime, SilcMime part);
 352
 353 /****f* silcutil/SILCMIMEAPI/silc_mime_is_multipart
 354  *
 355  * SYNOPSIS
 356  *
 357  *    SilcBool silc_mime_is_multipart(SilcMime mime);
 358  *
 359  * DESCRIPTION
 360  *
 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.
 363  *
 364  ***/
 365 SilcBool silc_mime_is_multipart(SilcMime mime);
 366
 367 /****f* silcutil/SILCMIMEAPI/silc_mime_get_multiparts
 368  *
 369  * SYNOPSIS
 370  *
 371  *    SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
 372  *
 373  * DESCRIPTION
 374  *
 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.
 380  *
 381  ***/
 382 SilcDList silc_mime_get_multiparts(SilcMime mime, const char **type);
 383
 384 #include "silcmime_i.h"
 385
 386 #endif /* SILCMIME_H */