1 /* ====================================================================
2  * The Kannel Software License, Version 1.0
3  *
4  * Copyright (c) 2001-2014 Kannel Group
5  * Copyright (c) 1998-2001 WapIT Ltd.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  *    notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  *    notice, this list of conditions and the following disclaimer in
17  *    the documentation and/or other materials provided with the
18  *    distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  *    if any, must include the following acknowledgment:
22  *       "This product includes software developed by the
23  *        Kannel Group (http://www.kannel.org/)."
24  *    Alternately, this acknowledgment may appear in the software itself,
25  *    if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Kannel" and "Kannel Group" must not be used to
28  *    endorse or promote products derived from this software without
29  *    prior written permission. For written permission, please
30  *    contact org@kannel.org.
31  *
32  * 5. Products derived from this software may not be called "Kannel",
33  *    nor may "Kannel" appear in their name, without prior written
34  *    permission of the Kannel Group.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED.  IN NO EVENT SHALL THE KANNEL GROUP OR ITS CONTRIBUTORS
40  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
41  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
42  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
43  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
44  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
45  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
46  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of the Kannel Group.  For more information on
51  * the Kannel Group, please see <http://www.kannel.org/>.
52  *
53  * Portions of this software are based upon software originally written at
54  * WapIT Ltd., Helsinki, Finland for the Kannel project.
55  */
56 
57 /*
58  * mime.h - Implement MIME multipart/related handling
59  *
60  * References:
61  *   RFC 2387 (The MIME Multipart/Related Content-type)
62  *   RFC 2025 (Multipurpose Internet Mail Extensions [MIME])
63  *
64  * Here we implement generic parsing functions to handle MIME multipart/related
65  * messages. Our representation is made by the struct MIMEEntity where each
66  * entity of the MIME scope is hold. Every entity should at least have headers.
67  * If the body is a "normal" content-type, then it is stored in Octstr *body.
68  * if the body is a sub-MIME multipart/related again, then it's single entities
69  * are parsed and chained into the List *multiparts. Hence items in the list
70  * are of type MIMEEntity again. We result in a recursive linked represenation
71  * of the MIME multipart/related structure.
72  *
73  * We know about two various multipart types:
74  *   multipart/mixed - where no "order" is associated among the entities
75  *   multipart/related - where the "start" parameter in the Content-Type defines
76  *                       the semantically main processing entitiy in the set.
77  *
78  * In order to provide a mapping facility between the MIMEEntity representation
79  * and an Octstr that holds the MIME document we have the two major functions
80  * mime_octstr_to_entity() and mime_entity_to_octstr() that act as converters.
81  *
82  * Using the MIMEEntity representation structure it is easier to handle the
83  * subsequent MIME entities in case we have a cubed structure in the document.
84  *
85  * Stipe Tolj <stolj@wapme.de>
86  */
87 
88 #ifndef MIME_H
89 #define MIME_H
90 
91 #include "gwlib/gwlib.h"
92 
93 
94 /* Define an generic MIME entity structure to be
95  * used for MIME multipart parsing. */
96 typedef struct MIMEEntity MIMEEntity;
97 
98 
99 /* create and destroy MIME multipart entity */
100 MIMEEntity *mime_entity_create(void);
101 void mime_entity_destroy(MIMEEntity *e);
102 
103 /* make a copy of a MIME object. */
104 MIMEEntity *mime_entity_duplicate(MIMEEntity *e);
105 
106 
107 /* Replace top-level MIME headers: Old ones removed completetly */
108 void mime_replace_headers(MIMEEntity *e, List *headers);
109 
110 
111 /* Get number of body parts. Returns 0 if this is not
112  * a multipart object.
113  */
114 int mime_entity_num_parts(MIMEEntity *e);
115 
116 /* Append  a new part to list of body parts. Copy is made*/
117 void mime_entity_add_part(MIMEEntity *e, MIMEEntity *part);
118 
119 /* Get part i in list of body parts. Copy is made*/
120 MIMEEntity *mime_entity_get_part(MIMEEntity *e, int i);
121 
122 /* Replace part i in list of body parts.  Old one will be deleted */
123 void mime_entity_replace_part(MIMEEntity *e, int i, MIMEEntity *newpart);
124 
125 /* Remove part i in list of body parts. */
126 void mime_entity_remove_part(MIMEEntity *e, int i);
127 
128 /* Change body element of non-multipart entity. */
129 void mime_entity_set_body(MIMEEntity *e, Octstr *body);
130 
131 /* Returns (copy of) the 'start' element of a multi-part entity. */
132 MIMEEntity *mime_multipart_start_elem(MIMEEntity *e);
133 
134 /*
135  * Parse the given Octstr that contains a normative text representation
136  * of the MIME multipart document into our representation strucuture.
137  * Will return parts of it in case an error occures in the recursive
138  * call, otherwise will return NULL in case of a fatal error while parsing.
139  */
140 MIMEEntity *mime_octstr_to_entity(Octstr *mime);
141 
142 /*
143  * Parse the given List (HTTP hedaer) and Octstr (HTTP body) and create
144  * a MIME multipart representatin if possible. Return NULL if parsing fails.
145  */
146 MIMEEntity *mime_http_to_entity(List *headers, Octstr *body);
147 
148 /*
149  * Convert a given MIME multipart representation structure to
150  * it's Octstr counterpart and return it. Will return parts of it,
151  * in case an error occures in a deeper level, otherwise a NULL
152  * is return in case of a fatal error while convertion.
153  */
154 Octstr *mime_entity_to_octstr(MIMEEntity *m);
155 
156 /*
157  * Take a MIME multipart representation and return the global header
158  * for it. Return a pointer to a HTTP header List.
159  */
160 List *mime_entity_headers(MIMEEntity *m);
161 
162 /*
163  * Take a MIME multipart representation and return the highest level
164  * body encoded to an Octstr to tbe used as HTTP POST body.
165  * Rerturns an Octstr with the body.
166  */
167 Octstr *mime_entity_body(MIMEEntity *m);
168 
169 /*
170  * Dump the structure (hicharchical view) of the MIME representation
171  * structure into our DEBUG log level facility.
172  */
173 void mime_entity_dump(MIMEEntity *m);
174 
175 
176 #endif
177