Mercurial > pidgin3 / file comparison

comparison: src/mime.h

src/mime.h

changeset 14253
b63ebf84c42b
parent 14252
d10dda2777a9
child 14254
77edc7a6191a
equal deleted inserted replaced
14252:d10dda2777a9 14253:b63ebf84c42b
1 /*
2 * Gaim
3 *
4 * Gaim 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 _GAIM_MIME_H
25 #define _GAIM_MIME_H
26
27 #include <glib.h>
28 #include <glib/glist.h>
29
30 /**
31 * @file mime.h
32 * @ingroup core
33 *
34 * Rudimentary parsing of multi-part MIME messages into more
35 * accessible structures.
36 */
37
38 /**
39 * @typedef GaimMimeDocument A MIME document.
40 */
41 typedef struct _GaimMimeDocument GaimMimeDocument;
42
43 /**
44 * @typedef GaimMimePart A part of a multipart MIME document.
45 */
46 typedef struct _GaimMimePart GaimMimePart;
47
48 /**
49 * Allocate an empty MIME document.
50 */
51 GaimMimeDocument *gaim_mime_document_new(void);
52
53 /**
54 * Frees memory used in a MIME document and all of its parts and fields
55 *
56 * @param doc The MIME document to free.
57 */
58 void gaim_mime_document_free(GaimMimeDocument *doc);
59
60 /**
61 * Parse a MIME document from a NUL-terminated string.
62 *
63 * @param buf The NULL-terminated string containing the MIME-encoded data.
64 *
65 * @returns A MIME document.
66 */
67 GaimMimeDocument *gaim_mime_document_parse(const char *buf);
68
69 /**
70 * Parse a MIME document from a string
71 *
72 * @param buf The string containing the MIME-encoded data.
73 * @param len Length of buf.
74 *
75 * @returns A MIME document.
76 */
77 GaimMimeDocument *gaim_mime_document_parsen(const char *buf, gsize len);
78
79 /**
80 * Write (append) a MIME document onto a GString.
81 */
82 void gaim_mime_document_write(GaimMimeDocument *doc, GString *str);
83
84 /**
85 * The list of fields in the header of a document
86 *
87 * @param doc The MIME document.
88 *
89 * @returns A list of strings indicating the fields (but not the values of
90 * the fields) in the header of doc.
91 */
92 const GList *gaim_mime_document_get_fields(GaimMimeDocument *doc);
93
94 /**
95 * Get the value of a specific field in the header of a document.
96 *
97 * @param doc The MIME document.
98 * @param field Case-insensitive field name.
99 *
100 * @returns Value associated with the indicated header field, or
101 * NULL if the field doesn't exist.
102 */
103 const char *gaim_mime_document_get_field(GaimMimeDocument *doc,
104 const char *field);
105
106 /**
107 * Set or replace the value of a specific field in the header of a
108 * document.
109 *
110 * @param doc The MIME document.
111 * @param field Case-insensitive field name.
112 * @param value Value to associate with the indicated header field,
113 * of NULL to remove the field.
114 */
115 void gaim_mime_document_set_field(GaimMimeDocument *doc,
116 const char *field,
117 const char *value);
118
119 /**
120 * The list of parts in a multipart document.
121 *
122 * @param doc The MIME document.
123 *
124 * @returns List of GaimMimePart contained within doc.
125 */
126 const GList *gaim_mime_document_get_parts(GaimMimeDocument *doc);
127
128 /**
129 * Create and insert a new part into a MIME document.
130 *
131 * @param doc The new part's parent MIME document.
132 */
133 GaimMimePart *gaim_mime_part_new(GaimMimeDocument *doc);
134
135
136 /**
137 * The list of fields in the header of a document part.
138 *
139 * @param part The MIME document part.
140 *
141 * @returns List of strings indicating the fields (but not the values
142 * of the fields) in the header of part.
143 */
144 const GList *gaim_mime_part_get_fields(GaimMimePart *part);
145
146
147 /**
148 * Get the value of a specific field in the header of a document part.
149 *
150 * @param part The MIME document part.
151 * @param field Case-insensitive name of the header field.
152 *
153 * @returns Value of the specified header field, or NULL if the
154 * field doesn't exist.
155 */
156 const char *gaim_mime_part_get_field(GaimMimePart *part,
157 const char *field);
158
159 /**
160 * Get the decoded value of a specific field in the header of a
161 * document part.
162 */
163 char *gaim_mime_part_get_field_decoded(GaimMimePart *part,
164 const char *field);
165
166 /**
167 * Set or replace the value of a specific field in the header of a
168 * document.
169 *
170 * @param part The part of the MIME document.
171 * @param field Case-insensitive field name
172 * @param value Value to associate with the indicated header field,
173 * of NULL to remove the field.
174 */
175 void gaim_mime_part_set_field(GaimMimePart *part,
176 const char *field,
177 const char *value);
178
179 /**
180 * Get the (possibly encoded) data portion of a MIME document part.
181 *
182 * @param part The MIME document part.
183 *
184 * @returns NULL-terminated data found in the document part
185 */
186 const char *gaim_mime_part_get_data(GaimMimePart *part);
187
188 /**
189 * Get the data portion of a MIME document part, after attempting to
190 * decode it according to the content-transfer-encoding field. If the
191 * specified encoding method is not supported, this function will
192 * return NULL.
193 *
194 * @param part The MIME documemt part.
195 * @param data Buffer for the data.
196 * @param len The length of the buffer.
197 */
198 void gaim_mime_part_get_data_decoded(GaimMimePart *part,
199 guchar **data, gsize *len);
200
201 /**
202 * Get the length of the data portion of a MIME document part.
203 *
204 * @param part The MIME document part.
205 * @returns Length of the data in the document part.
206 */
207 gsize gaim_mime_part_get_length(GaimMimePart *part);
208
209 void gaim_mime_part_set_data(GaimMimePart *part, const char *data);
210
211 #endif

Mercurial Repository: pidgin3

mercurial