368 lines
10 KiB
C
368 lines
10 KiB
C
/**@file sofia-sip/sip_protos.h.in
|
||
*
|
||
* Template for <sip_protos.h>.
|
||
*/
|
||
|
||
/* -*- C -*-
|
||
*
|
||
* This file is part of the Sofia-SIP package
|
||
*
|
||
* Copyright (C) 2005 Nokia Corporation.
|
||
*
|
||
* Contact: Pekka Pessi <pekka.pessi@nokia.com>
|
||
*
|
||
* This library is free software; you can redistribute it and/or
|
||
* modify it under the terms of the GNU Lesser General Public License
|
||
* as published by the Free Software Foundation; either version 2.1 of
|
||
* the License, or (at your option) any later version.
|
||
*
|
||
* This library is distributed in the hope that it will be useful, but
|
||
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
* Lesser General Public License for more details.
|
||
*
|
||
* You should have received a copy of the GNU Lesser General Public
|
||
* License along with this library; if not, write to the Free Software
|
||
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
|
||
* 02110-1301 USA
|
||
*
|
||
*/
|
||
|
||
#ifndef SIP_PROTOS_H
|
||
/** Defined when <sofia-sip/sip_protos.h> has been included. */
|
||
#define SIP_PROTOS_H
|
||
|
||
/**@file sofia-sip/sip_protos.h
|
||
*
|
||
* SIP prototypes and macros for each header.
|
||
*
|
||
* #AUTO#
|
||
*
|
||
* @author Pekka Pessi <Pekka.Pessi@nokia.com>.
|
||
*
|
||
*/
|
||
|
||
#include <sofia-sip/su_config.h>
|
||
|
||
#ifndef SIP_HEADER_H
|
||
#include <sofia-sip/sip_header.h>
|
||
#endif
|
||
|
||
#ifndef SIP_HCLASSES_H
|
||
#include <sofia-sip/sip_hclasses.h>
|
||
#endif
|
||
|
||
SOFIA_BEGIN_DECLS
|
||
|
||
#if SU_HAVE_INLINE
|
||
/** Get SIP structure from msg. */
|
||
su_inline
|
||
sip_t *sip_object(msg_t const *msg)
|
||
{
|
||
return (sip_t *)msg_public(msg, SIP_PROTOCOL_TAG);
|
||
}
|
||
|
||
/** Insert a (list of) header(s) to the header structure and fragment chain.
|
||
*
|
||
* The function @c sip_header_insert() inserts header or list of headers
|
||
* into a SIP message. It also inserts them into the the message fragment
|
||
* chain, if it exists.
|
||
*
|
||
* When inserting headers into the fragment chain, a request (or status) is
|
||
* inserted first and replaces the existing request (or status). The Via
|
||
* headers are inserted after the request or status, and rest of the headers
|
||
* after request, status, or Via headers.
|
||
*
|
||
* If the header is a singleton, existing headers with the same class are
|
||
* removed.
|
||
*
|
||
* @param msg message owning the fragment chain
|
||
* @param sip SIP message structure to which header is added
|
||
* @param h list of header(s) to be added
|
||
*/
|
||
su_inline
|
||
int sip_header_insert(msg_t *msg, sip_t *sip, sip_header_t *h)
|
||
{
|
||
return msg_header_insert(msg, (msg_pub_t *)sip, (msg_header_t *)h);
|
||
}
|
||
|
||
/** Remove a header from a SIP message. */
|
||
su_inline
|
||
int sip_header_remove(msg_t *msg, sip_t *sip, sip_header_t *h)
|
||
{
|
||
return msg_header_remove(msg, (msg_pub_t *)sip, (msg_header_t *)h);
|
||
}
|
||
|
||
/** Return name of the header. */
|
||
su_inline
|
||
char const *sip_header_name(sip_header_t const *h, int compact)
|
||
{
|
||
if (compact && h->sh_class->hc_short[0])
|
||
return h->sh_class->hc_short;
|
||
else
|
||
return h->sh_class->hc_name;
|
||
}
|
||
|
||
/** Return data after header structure. */
|
||
su_inline
|
||
void *sip_header_data(sip_header_t *h)
|
||
{
|
||
return h && h != SIP_NONE ? h->sh_class->hc_size + (char *)h : NULL;
|
||
}
|
||
#else
|
||
sip_t *sip_object(msg_t *msg);
|
||
int sip_header_insert(msg_t *msg, sip_t *sip, sip_header_t *h);
|
||
int sip_header_remove(msg_t *msg, sip_t *sip, sip_header_t *h);
|
||
char const *sip_header_name(sip_header_t const *h, int compact);
|
||
void *sip_header_data(sip_header_t *h);
|
||
#endif
|
||
|
||
/**@addtogroup sip_#xxxxxx#
|
||
* @{
|
||
*/
|
||
|
||
/** Parse a SIP @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#". @internal */
|
||
SOFIAPUBFUN issize_t sip_#xxxxxx#_d(su_home_t *, msg_header_t *,
|
||
char *s, isize_t slen);
|
||
|
||
/** Print a SIP @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#". @internal */
|
||
SOFIAPUBFUN issize_t sip_#xxxxxx#_e(char b[], isize_t bsiz,
|
||
msg_header_t const *h, int flags);
|
||
|
||
/**Access a SIP @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#"
|
||
* structure #sip_#xxxxxx#_t from #sip_t.
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#define sip_#xxxxxx#(sip) \
|
||
((sip_#xxxxxx#_t *)msg_header_access((msg_pub_t*)(sip), sip_#xxxxxx#_class))
|
||
|
||
/**Initializer for structure #sip_#xxxxxx#_t.
|
||
*
|
||
* A static #sip_#xxxxxx#_t structure for
|
||
* @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#" must be initialized with
|
||
* the SIP_#XXXXXX#_INIT() macro.
|
||
* For instance,
|
||
* @code
|
||
*
|
||
* sip_#xxxxxx#_t sip_#xxxxxx# = SIP_#XXXXXX#_INIT;
|
||
*
|
||
* @endcode
|
||
* @HI
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#define SIP_#XXXXXX#_INIT() SIP_HDR_INIT(#xxxxxx#)
|
||
|
||
/**Initialize a structure #sip_#xxxxxx#_t.
|
||
*
|
||
* An #sip_#xxxxxx#_t structure for
|
||
* @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#" can be initialized with the
|
||
* sip_#xxxxxx#_init() function/macro. For instance,
|
||
* @code
|
||
*
|
||
* sip_#xxxxxx#_t sip_#xxxxxx#;
|
||
*
|
||
* sip_#xxxxxx#_init(&sip_#xxxxxx#);
|
||
*
|
||
* @endcode
|
||
* @HI
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#if SU_HAVE_INLINE
|
||
su_inline sip_#xxxxxx#_t *sip_#xxxxxx#_init(sip_#xxxxxx#_t x[1])
|
||
{
|
||
return SIP_HEADER_INIT(x, sip_#xxxxxx#_class, sizeof(sip_#xxxxxx#_t));
|
||
}
|
||
#else
|
||
#define sip_#xxxxxx#_init(x) \
|
||
SIP_HEADER_INIT(x, sip_#xxxxxx#_class, sizeof(sip_#xxxxxx#_t))
|
||
#endif
|
||
|
||
/**Test if header object is instance of #sip_#xxxxxx#_t.
|
||
*
|
||
* Check if the header class is an instance of
|
||
* @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#" object and return true (nonzero),
|
||
* otherwise return false (zero).
|
||
*
|
||
* @param header pointer to the header structure to be tested
|
||
*
|
||
* @retval 1 (true) if the @a header is an instance of header #xxxxxx#
|
||
* @retval 0 (false) otherwise
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#if SU_HAVE_INLINE
|
||
su_inline int sip_is_#xxxxxx#(sip_header_t const *header)
|
||
{
|
||
return header && header->sh_class->hc_hash == sip_#xxxxxx#_hash;
|
||
}
|
||
#else
|
||
int sip_is_#xxxxxx#(sip_header_t const *header);
|
||
#endif
|
||
|
||
#define sip_#xxxxxx#_p(h) sip_is_#xxxxxx#((h))
|
||
|
||
|
||
/**Duplicate a list of @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#" header structures #sip_#xxxxxx#_t.
|
||
*
|
||
* Duplicate a header
|
||
* structure @a hdr. If the header structure @a hdr
|
||
* contains a reference (@c hdr->x_next) to a list of
|
||
* headers, all the headers in the list are duplicated, too.
|
||
*
|
||
* @param home memory home used to allocate new structure
|
||
* @param hdr header structure to be duplicated
|
||
*
|
||
* When duplicating, all parameter lists and non-constant
|
||
* strings attached to the header are copied, too. The
|
||
* function uses given memory @a home to allocate all the
|
||
* memory areas used to copy the header.
|
||
*
|
||
* @par Example
|
||
* @code
|
||
*
|
||
* #xxxxxx# = sip_#xxxxxx#_dup(home, sip->sip_#xxxxxx#);
|
||
*
|
||
* @endcode
|
||
*
|
||
* @return
|
||
* A pointer to the
|
||
* newly duplicated #sip_#xxxxxx#_t header structure, or NULL
|
||
* upon an error.
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#if SU_HAVE_INLINE
|
||
su_inline
|
||
#endif
|
||
sip_#xxxxxx#_t *sip_#xxxxxx#_dup(su_home_t *home, sip_#xxxxxx#_t const *hdr)
|
||
__attribute__((__malloc__));
|
||
|
||
#if SU_HAVE_INLINE
|
||
su_inline
|
||
sip_#xxxxxx#_t *sip_#xxxxxx#_dup(su_home_t *home, sip_#xxxxxx#_t const *hdr)
|
||
{
|
||
return (sip_#xxxxxx#_t *)
|
||
msg_header_dup_as(home, sip_#xxxxxx#_class, (msg_header_t const *)hdr);
|
||
}
|
||
#endif
|
||
|
||
/**Copy a list of @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#" header structures #sip_#xxxxxx#_t.
|
||
*
|
||
* The function sip_#xxxxxx#_copy() copies a header structure @a
|
||
* hdr. If the header structure @a hdr contains a reference (@c
|
||
* hdr->h_next) to a list of headers, all the headers in that
|
||
* list are copied, too. The function uses given memory @a home
|
||
* to allocate all the memory areas used to copy the list of header
|
||
* structure @a hdr.
|
||
*
|
||
* @param home memory home used to allocate new structure
|
||
* @param hdr pointer to the header structure to be copied
|
||
*
|
||
* When copying, only the header structure and parameter lists attached to
|
||
* it are duplicated. The new header structure retains all the references to
|
||
* the strings within the old @a hdr header, including the encoding of the
|
||
* old header, if present.
|
||
*
|
||
* @par Example
|
||
* @code
|
||
*
|
||
* #xxxxxx# = sip_#xxxxxx#_copy(home, sip->sip_#xxxxxx#);
|
||
*
|
||
* @endcode
|
||
*
|
||
* @return
|
||
* A pointer to newly copied header structure, or NULL upon an error.
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#if SU_HAVE_INLINE
|
||
su_inline
|
||
#endif
|
||
sip_#xxxxxx#_t *sip_#xxxxxx#_copy(su_home_t *home, sip_#xxxxxx#_t const *hdr)
|
||
__attribute__((__malloc__));
|
||
|
||
#if SU_HAVE_INLINE
|
||
su_inline
|
||
sip_#xxxxxx#_t *sip_#xxxxxx#_copy(su_home_t *home, sip_#xxxxxx#_t const *hdr)
|
||
{
|
||
return (sip_#xxxxxx#_t *)
|
||
msg_header_copy_as(home, sip_#xxxxxx#_class, (msg_header_t const *)hdr);
|
||
}
|
||
#endif
|
||
|
||
/**Make a @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#" structure #sip_#xxxxxx#_t.
|
||
*
|
||
* The function sip_#xxxxxx#_make() makes a new
|
||
* #sip_#xxxxxx#_t header structure. It allocates a new
|
||
* header structure, and decodes the string @a s as the
|
||
* value of the structure.
|
||
*
|
||
* @param home memory home used to allocate new header structure.
|
||
* @param s string to be decoded as value of the new header structure
|
||
*
|
||
* @return
|
||
* A pointer to newly maked #sip_#xxxxxx#_t header structure, or NULL upon an
|
||
* error.
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#if SU_HAVE_INLINE
|
||
su_inline
|
||
#endif
|
||
sip_#xxxxxx#_t *sip_#xxxxxx#_make(su_home_t *home, char const *s)
|
||
__attribute__((__malloc__));
|
||
|
||
#if SU_HAVE_INLINE
|
||
su_inline sip_#xxxxxx#_t *sip_#xxxxxx#_make(su_home_t *home, char const *s)
|
||
{
|
||
return (sip_#xxxxxx#_t *)sip_header_make(home, sip_#xxxxxx#_class, s);
|
||
}
|
||
#endif
|
||
|
||
/**Make a @ref sip_#xxxxxx# "#xxxxxxx_xxxxxxx#" from formatting result.
|
||
*
|
||
* Make a new #sip_#xxxxxx#_t object using formatting result as its value.
|
||
* The function first prints the arguments according to the format @a fmt
|
||
* specified. Then it allocates a new header structure, and parses the
|
||
* formatting result to the structure #sip_#xxxxxx#_t.
|
||
*
|
||
* @param home memory home used to allocate new header structure.
|
||
* @param fmt string used as a printf()-style format
|
||
* @param ... argument list for format
|
||
*
|
||
* @return
|
||
* A pointer to newly
|
||
* makes header structure, or NULL upon an error.
|
||
*
|
||
* @HIDE
|
||
*
|
||
* @since New in #version#.
|
||
*/
|
||
#if SU_HAVE_INLINE
|
||
su_inline
|
||
#endif
|
||
sip_#xxxxxx#_t *sip_#xxxxxx#_format(su_home_t *home, char const *fmt, ...)
|
||
__attribute__((__malloc__, __format__ (printf, 2, 3)));
|
||
|
||
#if SU_HAVE_INLINE
|
||
su_inline sip_#xxxxxx#_t *sip_#xxxxxx#_format(su_home_t *home, char const *fmt, ...)
|
||
{
|
||
sip_header_t *h;
|
||
va_list ap;
|
||
|
||
va_start(ap, fmt);
|
||
h = sip_header_vformat(home, sip_#xxxxxx#_class, fmt, ap);
|
||
va_end(ap);
|
||
|
||
return (sip_#xxxxxx#_t *)h;
|
||
}
|
||
#endif
|
||
|
||
/** @} */
|
||
|
||
SOFIA_END_DECLS
|
||
#endif /* !defined(SIP_PROTOS_H) */
|