Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/mime.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     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