more header removal/normalization
[asterisk/asterisk.git] / main / minimime / mm.h
1 /*
2  * $Id$
3  *
4  * MiniMIME - a library for handling MIME messages
5  *
6  * Copyright (C) 2003 Jann Fischer <rezine@mistrust.net>
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright
14  *    notice, this list of conditions and the following disclaimer.
15  * 2. Redistributions in binary form must reproduce the above copyright
16  *    notice, this list of conditions and the following disclaimer in the
17  *    documentation and/or other materials provided with the distribution.
18  * 3. Neither the name of the author nor the names of the contributors
19  *    may be used to endorse or promote products derived from this software
20  *    without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY JANN FISCHER AND CONTRIBUTORS ``AS IS'' AND
23  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25  * ARE DISCLAIMED.  IN NO EVENT SHALL JANN FISCHER OR THE VOICES IN HIS HEAD
26  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
32  * THE POSSIBILITY OF SUCH DAMAGE.
33  */
34
35 #ifndef _MM_H_INCLUDED
36 #define _MM_H_INCLUDED
37
38 #include "asterisk.h"
39 #include "mm_queue.h"
40 #include "mm_mem.h"
41
42 #define MM_MIME_LINELEN 998
43 #define MM_BASE64_LINELEN 76
44
45 TAILQ_HEAD(mm_mimeheaders, mm_mimeheader);
46 TAILQ_HEAD(mm_mimeparts, mm_mimepart);
47 TAILQ_HEAD(mm_params, mm_param);
48 SLIST_HEAD(mm_codecs, mm_codec);
49 SLIST_HEAD(mm_warnings, mm_warning);
50
51 /*
52  * Parser modes
53  */
54 enum mm_parsemodes
55 {
56         /** Parse loosely, accept some MIME quirks */
57         MM_PARSE_LOOSE = 0,
58         /** Parse as strict as possible */
59         MM_PARSE_STRICT
60 };
61
62 /*
63  * Available parser flags
64  */
65 enum mm_parseflags
66 {
67         MM_PARSE_NONE = (1L << 0),
68         MM_PARSE_STRIPCOMMENTS = (1L << 1)
69 };
70
71 /*
72  * Enumeration of MIME encodings
73  */
74 enum mm_encoding
75 {
76         MM_ENCODING_NONE = 0,
77         MM_ENCODING_BASE64,
78         MM_ENCODING_QUOTEDPRINTABLE,
79         MM_ENCODING_UNKNOWN
80 };
81
82 /*
83  * Message type
84  */
85 enum mm_messagetype
86 {
87         /** Flat message */
88         MM_MSGTYPE_FLAT = 0,
89         /** Composite message */
90         MM_MSGTYPE_MULTIPART
91 };
92
93 /*
94  * Enumeration of error categories
95  */
96 enum mm_errors
97 {
98         MM_ERROR_NONE = 0,
99         MM_ERROR_UNDEF,
100         MM_ERROR_ERRNO, 
101         MM_ERROR_PARSE,         
102         MM_ERROR_MIME,
103         MM_ERROR_CODEC,
104         MM_ERROR_PROGRAM
105 };
106
107 enum mm_warning_ids
108 {
109         MM_WARN_NONE = 0,
110         MM_WARN_PARSE,
111         MM_WARN_MIME,
112         MM_WARN_CODEC
113 };
114
115 enum mm_addressfields {
116         MM_ADDR_TO = 0,
117         MM_ADDR_CC,
118         MM_ADDR_BCC,
119         MM_ADDR_FROM,
120         MM_ADDR_SENDER,
121         MM_ADDR_REPLY_TO
122 };
123
124 enum mm_flatten_flags {
125         MM_FLATTEN_NONE = 0,
126         MM_FLATTEN_SKIPENVELOPE = (1L << 1),
127         MM_FLATTEN_OPAQUE = (1L << 2),
128         MM_FLATTEN_NOPREAMBLE = (1L << 3)
129 };      
130
131 /*
132  * More information about an error
133  */
134 struct mm_error_data
135 {
136         int error_id;
137         int error_where;
138         int lineno;
139         char error_msg[128];
140 };
141
142 extern int mm_errno;
143 extern struct mm_error_data mm_error;
144
145 enum mm_warning_code
146 {
147         MM_WARNING_NONE = 0,
148         MM_WARNING_INVHDR,
149 };
150
151 /*
152  * A parser warning
153  */
154 struct mm_warning
155 {
156         enum mm_warning_code warning;
157         uint32_t lineno;
158         SLIST_ENTRY(mm_warning) next;
159 };
160
161 /*
162  * Representation of a MiniMIME codec object
163  */
164 struct mm_codec
165 {
166         enum mm_encoding id;
167         char *encoding;
168
169         char *(*encoder)(char *, uint32_t);
170         char *(*decoder)(char *);
171
172         SLIST_ENTRY(mm_codec) next;
173 };
174
175 /*
176  * Representation of a MIME Content-Type parameter
177  */
178 struct mm_param
179 {
180         char *name; 
181         char *value; 
182
183         TAILQ_ENTRY(mm_param) next;
184 };
185
186 /*
187  * Representation of a mail or MIME header field
188  */
189 struct mm_mimeheader
190 {
191         char *name; 
192         char *value;
193
194         struct mm_params params;
195
196         TAILQ_ENTRY(mm_mimeheader) next;
197 };
198
199 /*
200  * Representation of a MIME Content-Type object
201  */
202 struct mm_content
203 {
204         char *maintype;
205         char *subtype;
206         char *disposition_type;
207
208         struct mm_params type_params;
209         struct mm_params disposition_params;
210
211         char *encstring;
212         enum mm_encoding encoding;
213 };
214
215 /*
216  * Representation of a MIME part 
217  */
218 struct mm_mimepart
219 {
220         struct mm_mimeheaders headers;
221         
222         size_t opaque_length;
223         char *opaque_body;
224
225         size_t length;
226         char *body;
227
228         struct mm_content *type;
229
230         TAILQ_ENTRY(mm_mimepart) next;
231 };
232
233 /*
234  * Represantation of a MiniMIME context
235  */
236 struct mm_context
237 {
238         struct mm_mimeparts parts;
239         enum mm_messagetype messagetype;
240         struct mm_warnings warnings;
241         struct mm_codecs codecs;
242         char *boundary;
243         char *preamble;
244         size_t max_message_size;
245 };
246
247 typedef struct mm_context MM_CTX;
248 typedef struct mm_context mm_ctx_t;
249
250 char *mm_unquote(const char *);
251 char *mm_uncomment(const char *);
252 char *mm_stripchars(char *, char *);
253 char *mm_addchars(char *, char *, uint16_t);
254 int mm_gendate(char **);
255 void mm_striptrailing(char **, const char *);
256 int mm_mimeutil_genboundary(char *, size_t, char **);
257
258 int mm_library_init(void);
259 int mm_library_isinitialized(void);
260
261 int mm_parse_mem(MM_CTX *, const char *, int, int);
262 int mm_parse_file(MM_CTX *, const char *, int, int);
263 int mm_parse_fileptr(MM_CTX *, FILE *, int, int);
264
265 MM_CTX *mm_context_new(void);
266 void mm_context_free(MM_CTX *);
267 int mm_context_attachpart(MM_CTX *, struct mm_mimepart *);
268 int mm_context_deletepart(MM_CTX *, int, int);
269 int mm_context_countparts(MM_CTX *);
270 struct mm_mimepart *mm_context_getpart(MM_CTX *, int);
271 int mm_context_iscomposite(MM_CTX *);
272 int mm_context_haswarnings(MM_CTX *);
273 int mm_context_flatten(MM_CTX *, char **, size_t *, int);
274
275 int mm_envelope_getheaders(MM_CTX *, char **, size_t *);
276 int mm_envelope_setheader(MM_CTX *, const char *, const char *, ...);
277
278 struct mm_mimeheader *mm_mimeheader_new(void);
279 void mm_mimeheader_free(struct mm_mimeheader *);
280 struct mm_mimeheader *mm_mimeheader_generate(const char *, const char *);
281 int mm_mimeheader_uncomment(struct mm_mimeheader *);
282 int mm_mimeheader_uncommentbyname(struct mm_mimepart *, const char *);
283 int mm_mimeheader_uncommentall(struct mm_mimepart *);
284 int mm_mimeheader_tostring(struct mm_mimeheader *);
285 char *mm_mimeheader_getparambyname(struct mm_mimeheader *hdr, const char *name);
286 int mm_mimeheader_attachparam(struct mm_mimeheader *hdr, struct mm_param *param);
287
288 struct mm_mimepart *mm_mimepart_new(void);
289 void mm_mimepart_free(struct mm_mimepart *);
290 int mm_mimepart_attachheader(struct mm_mimepart *, struct mm_mimeheader *);
291 int mm_mimepart_countheaders(struct mm_mimepart *part);
292 int mm_mimepart_countheaderbyname(struct mm_mimepart *, const char *);
293 struct mm_mimeheader *mm_mimepart_getheaderbyname(struct mm_mimepart *, const char *, int);
294 const char *mm_mimepart_getheadervalue(struct mm_mimepart *, const char *, int);
295 int mm_mimepart_headers_start(struct mm_mimepart *, struct mm_mimeheader **);
296 struct mm_mimeheader *mm_mimepart_headers_next(struct mm_mimepart *, struct mm_mimeheader **);
297 char *mm_mimepart_decode(struct mm_mimepart *);
298 struct mm_content *mm_mimepart_getcontent(struct mm_mimepart *);
299 size_t mm_mimepart_getlength(struct mm_mimepart *);
300 char *mm_mimepart_getbody(struct mm_mimepart *, int);
301 void mm_mimepart_attachcontenttype(struct mm_mimepart *, struct mm_content *);
302 int mm_mimepart_setdefaultcontenttype(struct mm_mimepart *, int);
303 int mm_mimepart_flatten(struct mm_mimepart *, char **, size_t *, int);
304 struct mm_mimepart *mm_mimepart_fromfile(const char *);
305
306 struct mm_content *mm_content_new(void);
307 void mm_content_free(struct mm_content *);
308 int mm_content_attachtypeparam(struct mm_content *, struct mm_param *);
309 int mm_content_attachdispositionparam(struct mm_content *, struct mm_param *);
310 struct mm_content *mm_content_parse(const char *, int);
311 char *mm_content_gettypeparambyname(struct mm_content *, const char *);
312 char *mm_content_getdispositionparambyname(struct mm_content *, const char *);
313 struct mm_param *mm_content_gettypeparamobjbyname(struct mm_content *, const char *);
314 struct mm_param *mm_content_getdispositionparamobjbyname(struct mm_content *, const char *);
315 int mm_content_setmaintype(struct mm_content *, char *, int);
316 int mm_content_setsubtype(struct mm_content *, char *, int);
317 int mm_content_settype(struct mm_content *, const char *, ...);
318 int mm_content_setdispositiontype(struct mm_content *ct, char *value, int copy);
319 char *mm_content_getmaintype(struct mm_content *);
320 char *mm_content_getsubtype(struct mm_content *);
321 char *mm_content_gettype(struct mm_content *);
322 char *mm_content_getdispositiontype(struct mm_content *ct);
323 int mm_content_iscomposite(struct mm_content *);
324 int mm_content_isvalidencoding(const char *);
325 int mm_content_setencoding(struct mm_content *, const char *);
326 char *mm_content_typeparamstostring(struct mm_content *);
327 char *mm_content_dispositionparamstostring(struct mm_content *);
328 char *mm_content_tostring(struct mm_content *);
329
330 struct mm_param *mm_param_new(void);
331 void mm_param_free(struct mm_param *);
332
333 char *mm_flatten_mimepart(struct mm_mimepart *);
334 char *mm_flatten_context(MM_CTX *);
335
336 int mm_codec_isregistered(const char *);
337 int mm_codec_hasdecoder(const char *);
338 int mm_codec_hasencoder(const char *);
339 int mm_codec_register(const char *, char *(*encoder)(char *, uint32_t), char *(*decoder)(char *));
340 int mm_codec_unregister(const char *);
341 int mm_codec_unregisterall(void);
342 void mm_codec_registerdefaultcodecs(void);
343
344 char *mm_base64_decode(char *);
345 char *mm_base64_encode(char *, uint32_t);
346
347 void mm_error_init(void);
348 void mm_error_setmsg(const char *, ...);
349 void mm_error_setlineno(int lineno);
350 char *mm_error_string(void);
351 int mm_error_lineno(void);
352
353 void mm_warning_add(MM_CTX *, int, const char *, ...);
354 struct mm_warning *mm_warning_next(MM_CTX *, struct mm_warning **);
355
356 #ifndef HAVE_STRLCPY
357 size_t strlcpy(char *, const char *, size_t);
358 #endif /* ! HAVE_STRLCPY */
359 #ifndef HAVE_STRLCAT
360 size_t strlcat(char *, const char *, size_t);
361 #endif /* ! HAVE_STRLCAT */
362
363 #define MM_ISINIT() do { \
364         assert(mm_library_isinitialized() == 1); \
365 } while (0);
366
367 #endif /* ! _MM_H_INCLUDED */