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
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * @file mime.h
  35  * @ingroup core
  36  *
  37  * Rudimentary parsing of multi-part MIME messages into more
  38  * accessible structures.
  39  */
  40
  41 /**
  42  * A MIME document.
  43  */
  44 typedef struct _PurpleMimeDocument PurpleMimeDocument;
  45
  46 /**
  47  * A part of a multipart MIME document.
  48  */
  49 typedef struct _PurpleMimePart PurpleMimePart;
  50
  51 /**
  52  * Allocate an empty MIME document.
  53  */
  54 PurpleMimeDocument *purple_mime_document_new(void);
  55
  56 /**
  57  * Frees memory used in a MIME document and all of its parts and fields
  58  *
  59  * @param doc The MIME document to free.
  60  */
  61 void purple_mime_document_free(PurpleMimeDocument *doc);
  62
  63 /**
  64  * Parse a MIME document from a NUL-terminated string.
  65  *
  66  * @param buf The NULL-terminated string containing the MIME-encoded data.
  67  *
  68  * @returns A MIME document.
  69  */
  70 PurpleMimeDocument *purple_mime_document_parse(const char *buf);
  71
  72 /**
  73  * Parse a MIME document from a string
  74  *
  75  * @param buf The string containing the MIME-encoded data.
  76  * @param len Length of buf.
  77  *
  78  * @returns   A MIME document.
  79  */
  80 PurpleMimeDocument *purple_mime_document_parsen(const char *buf, gsize len);
  81
  82 /**
  83  * Write (append) a MIME document onto a GString.
  84  */
  85 void purple_mime_document_write(PurpleMimeDocument *doc, GString *str);
  86
  87 /**
  88  * The list of fields in the header of a document
  89  *
  90  * @param doc The MIME document.
  91  *
  92  * @constreturn A list of strings indicating the fields (but not the values
  93  *              of the fields) in the header of doc.
  94  */
  95 GList *purple_mime_document_get_fields(PurpleMimeDocument *doc);
  96
  97 /**
  98  * Get the value of a specific field in the header of a document.
  99  *
 100  * @param doc   The MIME document.
 101  * @param field Case-insensitive field name.
 102  *
 103  * @returns     Value associated with the indicated header field, or
 104  *              NULL if the field doesn't exist.
 105  */
 106 const char *purple_mime_document_get_field(PurpleMimeDocument *doc,
 107                                          const char *field);
 108
 109 /**
 110  * Set or replace the value of a specific field in the header of a
 111  * document.
 112  *
 113  * @param doc   The MIME document.
 114  * @param field Case-insensitive field name.
 115  * @param value Value to associate with the indicated header field,
 116  *              of NULL to remove the field.
 117  */
 118 void purple_mime_document_set_field(PurpleMimeDocument *doc,
 119                                   const char *field,
 120                                   const char *value);
 121
 122 /**
 123  * The list of parts in a multipart document.
 124  *
 125  * @param doc The MIME document.
 126  *
 127  * @constreturn   List of PurpleMimePart contained within doc.
 128  */
 129 GList *purple_mime_document_get_parts(PurpleMimeDocument *doc);
 130
 131 /**
 132  * Create and insert a new part into a MIME document.
 133  *
 134  * @param doc The new part's parent MIME document.
 135  */
 136 PurpleMimePart *purple_mime_part_new(PurpleMimeDocument *doc);
 137
 138
 139 /**
 140  * The list of fields in the header of a document part.
 141  *
 142  * @param part The MIME document part.
 143  *
 144  * @constreturn List of strings indicating the fields (but not the values
 145  *              of the fields) in the header of part.
 146  */
 147 GList *purple_mime_part_get_fields(PurpleMimePart *part);
 148
 149
 150 /**
 151  * Get the value of a specific field in the header of a document part.
 152  *
 153  * @param part  The MIME document part.
 154  * @param field Case-insensitive name of the header field.
 155  *
 156  * @returns     Value of the specified header field, or NULL if the
 157  *              field doesn't exist.
 158  */
 159 const char *purple_mime_part_get_field(PurpleMimePart *part,
 160                                      const char *field);
 161
 162 /**
 163  * Get the decoded value of a specific field in the header of a
 164  * document part.
 165  */
 166 char *purple_mime_part_get_field_decoded(PurpleMimePart *part,
 167                                        const char *field);
 168
 169 /**
 170  * Set or replace the value of a specific field in the header of a
 171  * document.
 172  *
 173  * @param part  The part of the MIME document.
 174  * @param field Case-insensitive field name
 175  * @param value Value to associate with the indicated header field,
 176  *              of NULL to remove the field.
 177  */
 178 void purple_mime_part_set_field(PurpleMimePart *part,
 179                               const char *field,
 180                               const char *value);
 181
 182 /**
 183  * Get the (possibly encoded) data portion of a MIME document part.
 184  *
 185  * @param part The MIME document part.
 186  *
 187  * @returns    NULL-terminated data found in the document part
 188  */
 189 const char *purple_mime_part_get_data(PurpleMimePart *part);
 190
 191 /**
 192  * Get the data portion of a MIME document part, after attempting to
 193  * decode it according to the content-transfer-encoding field. If the
 194  * specified encoding method is not supported, this function will
 195  * return NULL.
 196  *
 197  * @param part The MIME documemt part.
 198  * @param data Buffer for the data.
 199  * @param len  The length of the buffer.
 200  */
 201 void purple_mime_part_get_data_decoded(PurpleMimePart *part,
 202                                      guchar **data, gsize *len);
 203
 204 /**
 205  * Get the length of the data portion of a MIME document part.
 206  *
 207  * @param part The MIME document part.
 208  * @returns    Length of the data in the document part.
 209  */
 210 gsize purple_mime_part_get_length(PurpleMimePart *part);
 211
 212 void purple_mime_part_set_data(PurpleMimePart *part, const char *data);
 213
 214 #ifdef __cplusplus
 215 }
 216 #endif
 217
 218 #endif