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