home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / mime.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  5.9 KB  |  220 lines
  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., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  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.  * @returns   A list of strings indicating the fields (but not the values of
  94.  *            the fields) in the header of doc.
  95.  */
  96. const 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.  * @returns   List of PurpleMimePart contained within doc.
  129.  */
  130. const 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.  * @returns    List of strings indicating the fields (but not the values
  146.  *             of the fields) in the header of part.
  147.  */
  148. const 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
  220.