Mercurial > pidgin
comparison src/mime.h @ 14038:443aaa05a7c3
[gaim-migrate @ 16642]
Formatting/whitespace
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Sat, 05 Aug 2006 09:11:46 +0000 |
parents | fc464a0abccc |
children |
comparison
equal
deleted
inserted
replaced
14037:5dcd38744d43 | 14038:443aaa05a7c3 |
---|---|
1 | |
2 /* | 1 /* |
3 Gaim | 2 * Gaim |
4 | 3 * |
5 Gaim is the legal property of its developers, whose names are too | 4 * Gaim is the legal property of its developers, whose names are too |
6 numerous to list here. Please refer to the COPYRIGHT file distributed | 5 * numerous to list here. Please refer to the COPYRIGHT file distributed |
7 with this source distribution | 6 * with this source distribution |
8 | 7 * |
9 This program is free software; you can redistribute it and/or modify | 8 * This program is free software; you can redistribute it and/or modify |
10 it under the terms of the GNU General Public License as published by | 9 * it under the terms of the GNU General Public License as published by |
11 the Free Software Foundation; either version 2 of the License, or (at | 10 * the Free Software Foundation; either version 2 of the License, or (at |
12 your option) any later version. | 11 * your option) any later version. |
13 | 12 * |
14 This program is distributed in the hope that it will be useful, but | 13 * This program is distributed in the hope that it will be useful, but |
15 WITHOUT ANY WARRANTY; without even the implied warranty of | 14 * WITHOUT ANY WARRANTY; without even the implied warranty of |
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 General Public License for more details. | 16 * General Public License for more details. |
18 | 17 * |
19 You should have received a copy of the GNU General Public License | 18 * You should have received a copy of the GNU General Public License |
20 along with this program; if not, write to the Free Software | 19 * along with this program; if not, write to the Free Software |
21 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, | 20 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, |
22 USA. | 21 * USA. |
23 */ | 22 */ |
24 | 23 |
25 #ifndef _GAIM_MIME_H | 24 #ifndef _GAIM_MIME_H |
26 #define _GAIM_MIME_H | 25 #define _GAIM_MIME_H |
27 | 26 |
28 | |
29 #include <glib.h> | 27 #include <glib.h> |
30 #include <glib/glist.h> | 28 #include <glib/glist.h> |
31 | 29 |
32 | 30 /** |
33 /** | 31 * @file mime.h |
34 @file mime.h | 32 * @ingroup core |
35 @ingroup core | 33 * |
36 | 34 * Rudimentary parsing of multi-part MIME messages into more |
37 Rudimentary parsing of multi-part MIME messages into more | 35 * accessible structures. |
38 accessible structures. | 36 */ |
39 */ | 37 |
40 | 38 /** |
41 | 39 * @typedef GaimMimeDocument A MIME document. |
42 /** @typedef GaimMimeDocument | |
43 A MIME document | |
44 */ | 40 */ |
45 typedef struct _GaimMimeDocument GaimMimeDocument; | 41 typedef struct _GaimMimeDocument GaimMimeDocument; |
46 | 42 |
47 | 43 /** |
48 /** @typedef GaimMimePart | 44 * @typedef GaimMimePart A part of a multipart MIME document. |
49 A part of a multipart MIME document | |
50 */ | 45 */ |
51 typedef struct _GaimMimePart GaimMimePart; | 46 typedef struct _GaimMimePart GaimMimePart; |
52 | 47 |
53 | 48 /** |
54 /** Allocate an empty MIME document */ | 49 * Allocate an empty MIME document. |
50 */ | |
55 GaimMimeDocument *gaim_mime_document_new(void); | 51 GaimMimeDocument *gaim_mime_document_new(void); |
56 | 52 |
57 | 53 /** |
58 /** Frees memory used in a MIME document and all of its parts and fields | 54 * Frees memory used in a MIME document and all of its parts and fields |
59 @param doc the MIME document to free | 55 * |
56 * @param doc The MIME document to free. | |
60 */ | 57 */ |
61 void gaim_mime_document_free(GaimMimeDocument *doc); | 58 void gaim_mime_document_free(GaimMimeDocument *doc); |
62 | 59 |
63 | 60 /** |
64 /** Parse a MIME document from a NUL-terminated string | 61 * Parse a MIME document from a NUL-terminated string. |
65 @param buf the NULL-terminated string containing the MIME-encoded data | 62 * |
66 @returns MIME document | 63 * @param buf The NULL-terminated string containing the MIME-encoded data. |
64 * | |
65 * @returns A MIME document. | |
67 */ | 66 */ |
68 GaimMimeDocument *gaim_mime_document_parse(const char *buf); | 67 GaimMimeDocument *gaim_mime_document_parse(const char *buf); |
69 | 68 |
70 | 69 /** |
71 /** Parse a MIME document from a string | 70 * Parse a MIME document from a string |
72 @param buf the string containing the MIME-encoded data | 71 * |
73 @param len length of buf | 72 * @param buf The string containing the MIME-encoded data. |
74 @returns MIME document | 73 * @param len Length of buf. |
74 * | |
75 * @returns A MIME document. | |
75 */ | 76 */ |
76 GaimMimeDocument *gaim_mime_document_parsen(const char *buf, gsize len); | 77 GaimMimeDocument *gaim_mime_document_parsen(const char *buf, gsize len); |
77 | 78 |
78 | 79 /** |
79 /** Write (append) a MIME document onto a GString */ | 80 * Write (append) a MIME document onto a GString. |
81 */ | |
80 void gaim_mime_document_write(GaimMimeDocument *doc, GString *str); | 82 void gaim_mime_document_write(GaimMimeDocument *doc, GString *str); |
81 | 83 |
82 | 84 /** |
83 /** The list of fields in the header of a document | 85 * The list of fields in the header of a document |
84 | 86 * |
85 @param doc the MIME document | 87 * @param doc The MIME document. |
86 @returns list of strings indicating the fields (but not the values of | 88 * |
87 the fields) in the header of doc | 89 * @returns A list of strings indicating the fields (but not the values of |
88 */ | 90 * the fields) in the header of doc. |
91 */ | |
89 const GList *gaim_mime_document_get_fields(GaimMimeDocument *doc); | 92 const GList *gaim_mime_document_get_fields(GaimMimeDocument *doc); |
90 | 93 |
91 | 94 /** |
92 /** Get the value of a specific field in the header of a document | 95 * Get the value of a specific field in the header of a document. |
93 | 96 * |
94 @param doc the MIME document | 97 * @param doc The MIME document. |
95 @param field case-insensitive field name | 98 * @param field Case-insensitive field name. |
96 @returns value associated with the indicated header field, or | 99 * |
97 NULL if the field doesn't exist | 100 * @returns Value associated with the indicated header field, or |
98 */ | 101 * NULL if the field doesn't exist. |
102 */ | |
99 const char *gaim_mime_document_get_field(GaimMimeDocument *doc, | 103 const char *gaim_mime_document_get_field(GaimMimeDocument *doc, |
100 const char *field); | 104 const char *field); |
101 | 105 |
102 | 106 /** |
103 /** Set or replace the value of a specific field in the header of a | 107 * Set or replace the value of a specific field in the header of a |
104 document | 108 * document. |
105 | 109 * |
106 @param doc the MIME document | 110 * @param doc The MIME document. |
107 @param field case-insensitive field name | 111 * @param field Case-insensitive field name. |
108 @param value value to associate with the indicated header field, | 112 * @param value Value to associate with the indicated header field, |
109 of NULL to remove the field | 113 * of NULL to remove the field. |
110 */ | 114 */ |
111 void gaim_mime_document_set_field(GaimMimeDocument *doc, | 115 void gaim_mime_document_set_field(GaimMimeDocument *doc, |
112 const char *field, | 116 const char *field, |
113 const char *value); | 117 const char *value); |
114 | 118 |
115 | 119 /** |
116 /** The list of parts in a multipart document | 120 * The list of parts in a multipart document. |
117 | 121 * |
118 @param doc the MIME document | 122 * @param doc The MIME document. |
119 @returns list of GaimMimePart contained within doc | 123 * |
120 */ | 124 * @returns List of GaimMimePart contained within doc. |
125 */ | |
121 const GList *gaim_mime_document_get_parts(GaimMimeDocument *doc); | 126 const GList *gaim_mime_document_get_parts(GaimMimeDocument *doc); |
122 | 127 |
123 | 128 /** |
124 /** Create and insert a new part into a MIME document | 129 * Create and insert a new part into a MIME document. |
125 | 130 * |
126 @param doc the new part's parent MIME document | 131 * @param doc The new part's parent MIME document. |
127 */ | 132 */ |
128 GaimMimePart *gaim_mime_part_new(GaimMimeDocument *doc); | 133 GaimMimePart *gaim_mime_part_new(GaimMimeDocument *doc); |
129 | 134 |
130 | 135 |
131 /** The list of fields in the header of a document part | 136 /** |
132 | 137 * The list of fields in the header of a document part. |
133 @param part the MIME document part | 138 * |
134 @returns list of strings indicating the fields (but not the values | 139 * @param part The MIME document part. |
135 of the fields) in the header of part | 140 * |
136 */ | 141 * @returns List of strings indicating the fields (but not the values |
142 * of the fields) in the header of part. | |
143 */ | |
137 const GList *gaim_mime_part_get_fields(GaimMimePart *part); | 144 const GList *gaim_mime_part_get_fields(GaimMimePart *part); |
138 | 145 |
139 | 146 |
140 /** Get the value of a specific field in the header of a document part | 147 /** |
141 | 148 * Get the value of a specific field in the header of a document part. |
142 @param part the MIME document part | 149 * |
143 @param field case-insensitive name of the header field | 150 * @param part The MIME document part. |
144 @returns value of the specified header field, or NULL if the | 151 * @param field Case-insensitive name of the header field. |
145 field doesn't exist | 152 * |
146 */ | 153 * @returns Value of the specified header field, or NULL if the |
154 * field doesn't exist. | |
155 */ | |
147 const char *gaim_mime_part_get_field(GaimMimePart *part, | 156 const char *gaim_mime_part_get_field(GaimMimePart *part, |
148 const char *field); | 157 const char *field); |
149 | 158 |
150 | 159 /** |
151 /** Get the decoded value of a specific field in the header of a | 160 * Get the decoded value of a specific field in the header of a |
152 document part */ | 161 * document part. |
162 */ | |
153 char *gaim_mime_part_get_field_decoded(GaimMimePart *part, | 163 char *gaim_mime_part_get_field_decoded(GaimMimePart *part, |
154 const char *field); | 164 const char *field); |
155 | 165 |
156 | 166 /** |
157 /** Set or replace the value of a specific field in the header of a | 167 * Set or replace the value of a specific field in the header of a |
158 document | 168 * document. |
159 @param part the part of the MIME document | 169 * |
160 @param field case-insensitive field name | 170 * @param part The part of the MIME document. |
161 @param value value to associate with the indicated header field, | 171 * @param field Case-insensitive field name |
162 of NULL to remove the field | 172 * @param value Value to associate with the indicated header field, |
163 */ | 173 * of NULL to remove the field. |
174 */ | |
164 void gaim_mime_part_set_field(GaimMimePart *part, | 175 void gaim_mime_part_set_field(GaimMimePart *part, |
165 const char *field, | 176 const char *field, |
166 const char *value); | 177 const char *value); |
167 | 178 |
168 | 179 /** |
169 /** Get the (possibly encoded) data portion of a MIME document part | 180 * Get the (possibly encoded) data portion of a MIME document part. |
170 @param part the MIME document part | 181 * |
171 @returns NULL-terminated data found in the document part | 182 * @param part The MIME document part. |
183 * | |
184 * @returns NULL-terminated data found in the document part | |
172 */ | 185 */ |
173 const char *gaim_mime_part_get_data(GaimMimePart *part); | 186 const char *gaim_mime_part_get_data(GaimMimePart *part); |
174 | 187 |
175 | 188 /** |
176 /** Get the data portion of a MIME document part, after attempting to | 189 * Get the data portion of a MIME document part, after attempting to |
177 decode it according to the content-transfer-encoding field. If the | 190 * decode it according to the content-transfer-encoding field. If the |
178 specified encoding method is not supported, this function will | 191 * specified encoding method is not supported, this function will |
179 return NULL. | 192 * return NULL. |
180 | 193 * |
181 @param part the MIME documemt part | 194 * @param part The MIME documemt part. |
182 @param data Buffer for the data | 195 * @param data Buffer for the data. |
183 @param len The length of the buffer | 196 * @param len The length of the buffer. |
184 */ | 197 */ |
185 void gaim_mime_part_get_data_decoded(GaimMimePart *part, | 198 void gaim_mime_part_get_data_decoded(GaimMimePart *part, |
186 guchar **data, gsize *len); | 199 guchar **data, gsize *len); |
187 | 200 |
188 | 201 /** |
189 /** Get the length of the data portion of a MIME document part | 202 * Get the length of the data portion of a MIME document part. |
190 | 203 * |
191 @param part the MIME document part | 204 * @param part The MIME document part. |
192 @returns length of the data in the document part | 205 * @returns Length of the data in the document part. |
193 */ | 206 */ |
194 gsize gaim_mime_part_get_length(GaimMimePart *part); | 207 gsize gaim_mime_part_get_length(GaimMimePart *part); |
195 | 208 |
196 | |
197 void gaim_mime_part_set_data(GaimMimePart *part, const char *data); | 209 void gaim_mime_part_set_data(GaimMimePart *part, const char *data); |
198 | 210 |
199 | |
200 #endif | 211 #endif |