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