libpurple/mime.h

   1 /*
   2  * Purple
   3  *
   4  * Purple is the legal property of its developers, whose names are too
   5  * numerous to list here. Please refer to the COPYRIGHT file distributed
   6  * with this source distribution
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or (at
  11  * your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301,
  21  * USA.
  22  */
  23
  24 #ifndef _PURPLE_MIME_H
  25 #define _PURPLE_MIME_H
  26
  27 #include <glib.h>
  28 #include <glib/glist.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @file mime.h
  36  * @ingroup core
  37  *
  38  * Rudimentary parsing of multi-part MIME messages into more
  39  * accessible structures.
  40  */
  41
  42 /**
  43  * A MIME document.
  44  */
  45 typedef struct _PurpleMimeDocument PurpleMimeDocument;
  46
  47 /**
  48  * A part of a multipart MIME document.
  49  */
  50 typedef struct _PurpleMimePart PurpleMimePart;
  51
  52 /**
  53  * Allocate an empty MIME document.
  54  */
  55 PurpleMimeDocument *purple_mime_document_new(void);
  56
  57 /**
  58  * Frees memory used in a MIME document and all of its parts and fields
  59  *
  60  * @param doc The MIME document to free.
  61  */
  62 void purple_mime_document_free(PurpleMimeDocument *doc);
  63
  64 /**
  65  * Parse a MIME document from a NUL-terminated string.
  66  *
  67  * @param buf The NULL-terminated string containing the MIME-encoded data.
  68  *
  69  * @returns A MIME document.
  70  */
  71 PurpleMimeDocument *purple_mime_document_parse(const char *buf);
  72
  73 /**
  74  * Parse a MIME document from a string
  75  *
  76  * @param buf The string containing the MIME-encoded data.
  77  * @param len Length of buf.
  78  *
  79  * @returns   A MIME document.
  80  */
  81 PurpleMimeDocument *purple_mime_document_parsen(const char *buf, gsize len);
  82
  83 /**
  84  * Write (append) a MIME document onto a GString.
  85  */
  86 void purple_mime_document_write(PurpleMimeDocument *doc, GString *str);
  87
  88 /**
  89  * The list of fields in the header of a document
  90  *
  91  * @param doc The MIME document.
  92  *
  93  * @constreturn A list of strings indicating the fields (but not the values
  94  *              of the fields) in the header of doc.
  95  */
  96 GList *purple_mime_document_get_fields(PurpleMimeDocument *doc);
  97
  98 /**
  99  * Get the value of a specific field in the header of a document.
 100  *
 101  * @param doc   The MIME document.
 102  * @param field Case-insensitive field name.
 103  *
 104  * @returns     Value associated with the indicated header field, or
 105  *              NULL if the field doesn't exist.
 106  */
 107 const char *purple_mime_document_get_field(PurpleMimeDocument *doc,
 108                                          const char *field);
 109
 110 /**
 111  * Set or replace the value of a specific field in the header of a
 112  * document.
 113  *
 114  * @param doc   The MIME document.
 115  * @param field Case-insensitive field name.
 116  * @param value Value to associate with the indicated header field,
 117  *              of NULL to remove the field.
 118  */
 119 void purple_mime_document_set_field(PurpleMimeDocument *doc,
 120                                   const char *field,
 121                                   const char *value);
 122
 123 /**
 124  * The list of parts in a multipart document.
 125  *
 126  * @param doc The MIME document.
 127  *
 128  * @constreturn   List of PurpleMimePart contained within doc.
 129  */
 130 GList *purple_mime_document_get_parts(PurpleMimeDocument *doc);
 131
 132 /**
 133  * Create and insert a new part into a MIME document.
 134  *
 135  * @param doc The new part's parent MIME document.
 136  */
 137 PurpleMimePart *purple_mime_part_new(PurpleMimeDocument *doc);
 138
 139
 140 /**
 141  * The list of fields in the header of a document part.
 142  *
 143  * @param part The MIME document part.
 144  *
 145  * @constreturn List of strings indicating the fields (but not the values
 146  *              of the fields) in the header of part.
 147  */
 148 GList *purple_mime_part_get_fields(PurpleMimePart *part);
 149
 150
 151 /**
 152  * Get the value of a specific field in the header of a document part.
 153  *
 154  * @param part  The MIME document part.
 155  * @param field Case-insensitive name of the header field.
 156  *
 157  * @returns     Value of the specified header field, or NULL if the
 158  *              field doesn't exist.
 159  */
 160 const char *purple_mime_part_get_field(PurpleMimePart *part,
 161                                      const char *field);
 162
 163 /**
 164  * Get the decoded value of a specific field in the header of a
 165  * document part.
 166  */
 167 char *purple_mime_part_get_field_decoded(PurpleMimePart *part,
 168                                        const char *field);
 169
 170 /**
 171  * Set or replace the value of a specific field in the header of a
 172  * document.
 173  *
 174  * @param part  The part of the MIME document.
 175  * @param field Case-insensitive field name
 176  * @param value Value to associate with the indicated header field,
 177  *              of NULL to remove the field.
 178  */
 179 void purple_mime_part_set_field(PurpleMimePart *part,
 180                               const char *field,
 181                               const char *value);
 182
 183 /**
 184  * Get the (possibly encoded) data portion of a MIME document part.
 185  *
 186  * @param part The MIME document part.
 187  *
 188  * @returns    NULL-terminated data found in the document part
 189  */
 190 const char *purple_mime_part_get_data(PurpleMimePart *part);
 191
 192 /**
 193  * Get the data portion of a MIME document part, after attempting to
 194  * decode it according to the content-transfer-encoding field. If the
 195  * specified encoding method is not supported, this function will
 196  * return NULL.
 197  *
 198  * @param part The MIME documemt part.
 199  * @param data Buffer for the data.
 200  * @param len  The length of the buffer.
 201  */
 202 void purple_mime_part_get_data_decoded(PurpleMimePart *part,
 203                                      guchar **data, gsize *len);
 204
 205 /**
 206  * Get the length of the data portion of a MIME document part.
 207  *
 208  * @param part The MIME document part.
 209  * @returns    Length of the data in the document part.
 210  */
 211 gsize purple_mime_part_get_length(PurpleMimePart *part);
 212
 213 void purple_mime_part_set_data(PurpleMimePart *part, const char *data);
 214
 215 #ifdef __cplusplus
 216 }
 217 #endif
 218
 219 #endif