Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjsip / include / pjsip / sip_multipart.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
18  */
19 #ifndef __PJSIP_SIP_MULTIPART_H__
20 #define __PJSIP_SIP_MULTIPART_H__
21
22 /**
23  * @file pjsip/sip_multipart.h
24  * @brief Multipart support.
25  */
26
27 #include <pjsip/sip_msg.h>
28
29 PJ_BEGIN_DECL
30
31 /**
32  * @defgroup PJSIP_MULTIPART Multipart message bodies.
33  * @ingroup PJSIP_MSG
34  * @brief Support for multipart message bodies.
35  * @{
36  */
37
38 /**
39  * This structure describes the individual body part inside a multipart
40  * message body. It mainly contains the message body itself and optional
41  * headers.
42  */
43 typedef struct pjsip_multipart_part
44 {
45     /**
46      * Standard list element.
47      */
48     PJ_DECL_LIST_MEMBER(struct pjsip_multipart_part);
49
50     /**
51      * Optional message headers.
52      */
53     pjsip_hdr               hdr;
54
55     /**
56      * Pointer to the message body.
57      */
58     pjsip_msg_body         *body;
59
60 } pjsip_multipart_part;
61
62 /**
63  * Create an empty multipart body.
64  *
65  * @param pool          Memory pool to allocate memory from.
66  * @param ctype         Optional MIME media type of the multipart
67  *                      bodies. If not specified, "multipart/mixed"
68  *                      will be used.
69  * @param boundary      Optional string to be set as part boundary.
70  *                      The boundary string excludes the leading
71  *                      hyphens. If this parameter is NULL or empty,
72  *                      a random boundary will be generated.
73  *
74  * @return              Multipart body instance with no part.
75  */
76 PJ_DECL(pjsip_msg_body*) pjsip_multipart_create(pj_pool_t *pool,
77                                                 const pjsip_media_type *ctype,
78                                                 const pj_str_t *boundary);
79
80 /**
81  * Create an empty multipart part.
82  *
83  * @param pool          The memory pool.
84  *
85  * @return              The multipart part.
86  */
87 PJ_DECL(pjsip_multipart_part*) pjsip_multipart_create_part(pj_pool_t *pool);
88
89
90 /**
91  * Perform a deep clone to a multipart part.
92  *
93  * @param pool          The memory pool.
94  * @param part          The part to be duplicated.
95  *
96  * @return              Copy of the multipart part.
97  */
98 PJ_DECL(pjsip_multipart_part*)
99 pjsip_multipart_clone_part(pj_pool_t *pool,
100                            const pjsip_multipart_part *part);
101
102 /**
103  * Add a part into multipart bodies.
104  *
105  * @param pool          The memory pool.
106  * @param mp            The multipart bodies.
107  * @param part          The part to be added into the bodies.
108  *
109  * @return              PJ_SUCCESS on success.
110  */
111 PJ_DECL(pj_status_t) pjsip_multipart_add_part(pj_pool_t *pool,
112                                               pjsip_msg_body *mp,
113                                               pjsip_multipart_part *part);
114
115 /**
116  * Get the first part of multipart bodies.
117  *
118  * @param mp            The multipart bodies.
119  *
120  * @return              The first part, or NULL if the multipart
121  *                      bodies currently doesn't hold any elements.
122  */
123 PJ_DECL(pjsip_multipart_part*)
124 pjsip_multipart_get_first_part(const pjsip_msg_body *mp);
125
126 /**
127  * Get the next part after the specified part.
128  *
129  * @param mp            The multipart bodies.
130  * @param part          The part.
131  *
132  * @return              The next part, or NULL if there is no other part after
133  *                      the part.
134  */
135 PJ_DECL(pjsip_multipart_part*)
136 pjsip_multipart_get_next_part(const pjsip_msg_body *mp,
137                               pjsip_multipart_part *part);
138
139 /**
140  * Find a body inside multipart bodies which has the specified content type.
141  *
142  * @param mp            The multipart body.
143  * @param content_type  Content type to find.
144  * @param start         If specified, the search will begin at
145  *                      start->next. Otherwise it will begin at
146  *                      the first part in the multipart bodies.
147  *
148  * @return              The first part with the specified content type
149  *                      if found, or NULL.
150  */
151 PJ_DECL(pjsip_multipart_part*)
152 pjsip_multipart_find_part( const pjsip_msg_body *mp,
153                            const pjsip_media_type *content_type,
154                            const pjsip_multipart_part *start);
155
156 /**
157  * Parse multipart message.
158  *
159  * @param pool          Memory pool.
160  * @param buf           Input buffer.
161  * @param len           The buffer length.
162  * @param ctype         Content type of the multipart body.
163  * @param options       Parsing options, must be zero for now.
164  *
165  * @return              Multipart message body.
166  */
167 PJ_DECL(pjsip_msg_body*) pjsip_multipart_parse(pj_pool_t *pool,
168                                                char *buf, pj_size_t len,
169                                                const pjsip_media_type *ctype,
170                                                unsigned options);
171
172 /**
173  * @}  PJSIP_MULTIPART
174  */
175
176
177 PJ_END_DECL
178
179 #endif  /* __PJSIP_SIP_MULTIPART_H__ */