/**@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) */
