1/**@ingroup msg  -*- c -*-
2 * @file sofia-sip/msg_mime_protos.h.in
3 *
4 * Template for <msg_mime_protos.h>.
5 */
6
7/*
8 * This file is part of the Sofia-SIP package
9 *
10 * Copyright (C) 2005 Nokia Corporation.
11 *
12 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
13 *
14 * This library is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU Lesser General Public License
16 * as published by the Free Software Foundation; either version 2.1 of
17 * the License, or (at your option) any later version.
18 *
19 * This library is distributed in the hope that it will be useful, but
20 * WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * Lesser General Public License for more details.
23 *
24 * You should have received a copy of the GNU Lesser General Public
25 * License along with this library; if not, write to the Free Software
26 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
27 * 02110-1301 USA
28 *
29 */
30
31#ifndef MSG_MIME_PROTOS_H
32/** Defined when <sofia-sip/msg_mime_protos.h> has been included. */
33#define MSG_MIME_PROTOS_H
34
35/**@ingroup msg_mime
36 * @file sofia-sip/msg_mime_protos.h
37 *
38 * Prototypes for MIME headers (@RFC2045).
39 *
40 * #AUTO#
41 *
42 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
43 */
44
45#ifndef MSG_PARSER_H
46#include <sofia-sip/msg_parser.h>
47#endif
48#ifndef MSG_MIME_H
49#include <sofia-sip/msg_mime.h>
50#endif
51#ifndef MSG_MCLASS_H
52#include <sofia-sip/msg_mclass.h>
53#endif
54#ifndef MSG_MCLASS_H
55#include <sofia-sip/msg_mclass.h>
56#endif
57
58SOFIA_BEGIN_DECLS
59
60MSG_DLL extern msg_mclass_t const msg_multipart_mclass[1];
61
62#define msg_multipart_class ((msg_hclass_t *)msg_multipart_mclass)
63
64
65/* Declare internal prototypes for #xxxxxxx_xxxxxxx# */
66
67/**@addtogroup msg_#xxxxxx#
68 * @{
69 */
70
71enum {
72  /** Hash of #xxxxxxx_xxxxxxx#. @internal */
73  msg_#xxxxxx#_hash = #hash#
74};
75
76/** Parse a #xxxxxxx_xxxxxxx#. @internal */
77MSG_DLL msg_parse_f msg_#xxxxxx#_d;
78
79/** Print a #xxxxxxx_xxxxxxx#. @internal */
80MSG_DLL msg_print_f msg_#xxxxxx#_e;
81
82MSG_DLL msg_xtra_f msg_#xxxxxx#_dup_xtra;
83MSG_DLL msg_dup_f msg_#xxxxxx#_dup_one;
84
85/**Header class for #xxxxxxx_xxxxxxx#.
86 *
87 * The header class msg_#xxxxxx#_class defines how a
88 * #xxxxxxx_xxxxxxx# header is parsed and printed.  It also
89 * contains methods used by message parser and other functions
90 * to manipulate the #msg_#xxxxxx#_t header structure.
91 *
92 */
93#ifndef msg_#xxxxxx#_class
94MSG_DLL extern msg_hclass_t msg_#xxxxxx#_class[];
95#endif
96
97/**Initializer for an #msg_#xxxxxx#_t structure.
98 *
99 * A static msg_#xxxxxx#_t structure must be initialized
100 * with the MSG_#XXXXXX#_INIT() macro. For instance,
101 * @code
102 *
103 *  msg_#xxxxxx#_t msg_#xxxxxx# = MSG_#XXXXXX#_INIT;
104 *
105 * @endcode
106 * @HI
107 */
108#define MSG_#XXXXXX#_INIT() MSG_HDR_INIT(#xxxxxx#)
109
110/**Initialize an #msg_#xxxxxx#_t structure.
111 *
112 * An #msg_#xxxxxx#_t structure can be initialized with the
113 * msg_#xxxxxx#_init() function/macro. For instance,
114 * @code
115 *
116 *  msg_#xxxxxx#_t msg_#xxxxxx#;
117 *
118 *  msg_#xxxxxx#_init(&msg_#xxxxxx#);
119 *
120 * @endcode
121 *
122 * @param x pointer to #msg_#xxxxxx#_t structure
123 */
124#if SU_HAVE_INLINE
125su_inline msg_#xxxxxx#_t *msg_#xxxxxx#_init(msg_#xxxxxx#_t x[1])
126{
127  return MSG_HEADER_INIT(x, msg_#xxxxxx#_class, sizeof(msg_#xxxxxx#_t));
128}
129#else
130#define msg_#xxxxxx#_init(x) \
131  MSG_HEADER_INIT(x, msg_#xxxxxx#_class, sizeof(msg_#xxxxxx#_t))
132#endif
133
134/**Test if header object is an instance of #msg_#xxxxxx#_t.
135 *
136 * The function msg_is_#xxxxxx#() returns true (nonzero) if
137 * the header class is an instance of #xxxxxxx_xxxxxxx#
138 * object and false (zero) otherwise.
139 *
140 * @param header pointer to the header structure to be tested
141 *
142 * @return The function msg_is_#xxxxxx#() returns true (nonzero) if the
143 * header object is an instance of header #xxxxxxx_xxxxxxx# and false (zero)
144 * otherwise.
145 */
146#if SU_HAVE_INLINE
147su_inline int msg_is_#xxxxxx#(msg_header_t const *header)
148{
149  return header && header->sh_class->hc_hash == msg_#xxxxxx#_hash;
150}
151#else
152int msg_is_#xxxxxx#(msg_header_t const *header);
153#endif
154
155#define msg_#xxxxxx#_p(h) msg_is_#xxxxxx#((h))
156
157/**Duplicate (deep copy) #msg_#xxxxxx#_t.
158 *
159 * The function msg_#xxxxxx#_dup() duplicates a header structure @a
160 * header. If the header structure @a header contains a reference
161 * (@c header->x_next) to a list of headers, all the headers in the
162 * list are duplicated, too.
163 *
164 * @param home   memory home used to allocate new structure
165 * @param header header structure to be duplicated
166 *
167 * When duplicating, all parameter lists and non-constant strings
168 * attached to the header are copied, too. The function uses given
169 * memory @a home to allocate all the memory areas used to copy the
170 * header.
171 *
172 * @par Example
173 * @code
174 *
175 *   #xxxxxx# = msg_#xxxxxx#_dup(home, msg->msg_#xxxxxx#);
176 *
177 * @endcode
178 *
179 * @return
180 * The function msg_#xxxxxx#_dup() returns a pointer to the
181 * newly duplicated #msg_#xxxxxx#_t header structure, or NULL
182 * upon an error.
183 */
184#if SU_HAVE_INLINE
185su_inline
186#endif
187msg_#xxxxxx#_t *msg_#xxxxxx#_dup(su_home_t *home,
188				 msg_#xxxxxx#_t const *header);
189
190#if SU_HAVE_INLINE
191su_inline
192msg_#xxxxxx#_t *msg_#xxxxxx#_dup(su_home_t *home,
193				 msg_#xxxxxx#_t const *header)
194{
195  return (msg_#xxxxxx#_t *)
196    msg_header_dup_as(home, msg_#xxxxxx#_class, (msg_header_t const *)header);
197}
198#endif
199
200
201/**Copy an #msg_#xxxxxx#_t header structure.
202 *
203 * The function msg_#xxxxxx#_copy() copies a header structure @a
204 * header. If the header structure @a header contains a reference
205 * (@c header->h_next) to a list of headers, all the headers in that
206 * list are copied, too. The function uses given memory @a home to
207 * allocate all the memory areas used to copy the header structure
208 * @a header.
209 *
210 * @param home    memory home used to allocate new structure
211 * @param header  pointer to the header structure to be duplicated
212 *
213 * When copying, only the header structure and parameter lists
214 * attached to it are duplicated. The new header structure retains
215 * all the references to the strings within the old @a header,
216 * including the encoding of the old header, if present.
217 *
218 * @par Example
219 * @code
220 *
221 *   #xxxxxx# = msg_#xxxxxx#_copy(home, msg->msg_#xxxxxx#);
222 *
223 * @endcode
224 *
225 * @return
226 * The function msg_#xxxxxx#_copy() returns a pointer to
227 * newly copied header structure, or NULL upon an error.
228 */
229#if SU_HAVE_INLINE
230su_inline
231#endif
232msg_#xxxxxx#_t *msg_#xxxxxx#_copy(su_home_t *home,
233				  msg_#xxxxxx#_t const *header);
234
235#if SU_HAVE_INLINE
236su_inline
237msg_#xxxxxx#_t *msg_#xxxxxx#_copy(su_home_t *home,
238				  msg_#xxxxxx#_t const *header)
239{
240  return (msg_#xxxxxx#_t *)
241    msg_header_copy_as(home, msg_#xxxxxx#_class, (msg_header_t const *)header);
242}
243#endif
244
245
246/**Make a header structure #msg_#xxxxxx#_t.
247 *
248 * The function msg_#xxxxxx#_make() makes a new #msg_#xxxxxx#_t header
249 * structure. It allocates a new header structure, and decodes the string @a
250 * s as the value of the structure.
251 *
252 * @param home memory home used to allocate new header structure.
253 * @param s    string to be decoded as value of the new header structure
254 *
255 * @note This function may be implemented as a macro calling
256 * msg_header_make().
257 *
258 * @return
259 * The function msg_#xxxxxx#_make() returns a pointer to newly maked
260 * #msg_#xxxxxx#_t header structure, or NULL upon an error.
261 */
262#if SU_HAVE_INLINE
263su_inline msg_#xxxxxx#_t *msg_#xxxxxx#_make(su_home_t *home, char const *s)
264{
265  return (msg_#xxxxxx#_t*)msg_header_make(home, msg_#xxxxxx#_class, s);
266}
267#else
268msg_#xxxxxx#_t *msg_#xxxxxx#_make(su_home_t *home, char const *s);
269#endif
270
271
272/**Make a #xxxxxxx_xxxxxxx# from formatting result.
273 *
274 * The function msg_#xxxxxx#_format() makes a new #xxxxxxx_xxxxxxx# object
275 * using snprintf-formatted result as its value. The function first
276 * prints the arguments according to the format @a fmt specified. Then it
277 * allocates a new header structure, and uses the formatting result as the
278 * header value.
279 *
280 * @param home   memory home used to allocate new header structure.
281 * @param fmt    string used as a printf()-style format
282 * @param ...    argument list for format
283 *
284 * @note This function may be implemented as a macro calling
285 * msg_header_format().
286 *
287 * @return
288 * The function msg_#xxxxxx#_format() returns a pointer to newly
289 * makes header structure, or NULL upon an error.
290 *
291 * @HIDE
292 */
293#if SU_HAVE_INLINE
294su_inline
295#endif
296msg_#xxxxxx#_t *msg_#xxxxxx#_format(su_home_t *home, char const *fmt, ...)
297     __attribute__((__format__ (printf, 2, 3)));
298
299#if SU_HAVE_INLINE
300su_inline msg_#xxxxxx#_t *msg_#xxxxxx#_format(su_home_t *home, char const *fmt, ...)
301{
302  msg_header_t *h;
303  va_list ap;
304
305  va_start(ap, fmt);
306  h = msg_header_vformat(home, msg_#xxxxxx#_class, fmt, ap);
307  va_end(ap);
308
309  return (msg_#xxxxxx#_t*)h;
310}
311#endif
312
313/** @} */
314
315
316/* Internal prototypes */
317MSG_DLL msg_update_f msg_accept_update;
318MSG_DLL msg_update_f msg_accept_any_update;
319MSG_DLL msg_update_f msg_content_disposition_update;
320
321SOFIA_END_DECLS
322
323#endif /** !defined(MSG_MIME_PROTOS_H) */
324