soa_tag.c

Sofia SIP is an open-source SIP User-Agent library, compliant with the IETF RFC3261 specification.

/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <[e-mail]>
 *
 * 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
 *
 */

/**@CFILE soa_tag.c  Tags and tag lists for Offer/Answer Engine
 *
 * @author Pekka Pessi <[e-mail]>
 *
 * @date Created: Wed Aug  3 20:28:17 EEST 2005
 */

#include "config.h"

#include <sofia-sip/su.h>

#if 1
#define TAG_NAMESPACE soa_tag_namespace
#else
/* Definition used by tag_dll.awk */
#define TAG_NAMESPACE "soa"
#endif

#include <sofia-sip/soa.h>
#include <sofia-sip/soa_tag.h>

#include <sofia-sip/su_tag_class.h>
#include <sofia-sip/sdp_tag.h>

#include <string.h>

char const soa_tag_namespace[] = "soa";

/** Filter soa tags. */
int soa_tag_filter(tagi_t const *f, tagi_t const *t)
{
  char const *ns;

  if (!t || !t->t_tag)
    return 0;

  ns = t->t_tag->tt_ns; 
  if (!ns)
    return 0;

  return ns == soa_tag_namespace || strcmp(ns, soa_tag_namespace) == 0;
}

/**@def SOATAG_ANY()
 * 
 * Filter tag matching any SOATAG_*() item.
 */
tag_typedef_t soatag_any = NSTAG_TYPEDEF(*);

/**@def SOATAG_CAPS_SDP(x)
 *  Pass parsed capability description to soa session object.
 *
 * @par Used with
 *    soa_set_params() \n
 *    soa_get_params() \n
 *
 * @par Parameter type
 *    #sdp_session_t *
 *
 * @par Values
 *    #sdp_session_t describing @soa capabilities
 *
 * Corresponding tag taking reference parameter is SOATAG_CAPS_SDP_REF()
 */
tag_typedef_t soatag_caps_sdp = SDPTAG_TYPEDEF(caps_sdp);

/**@def SOATAG_CAPS_SDP_STR(x)
 *  Pass capability description to @soa session object.
 *
 * @par Used with
 *    soa_set_param() \n
 *    soa_get_params() \n
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *    String containing SDP description of @soa capabilities
 *
 * Corresponding tag taking reference parameter is SOATAG_CAPS_SDP_STR_REF()
 */
tag_typedef_t soatag_caps_sdp_str = STRTAG_TYPEDEF(caps_sdp_str);

/**@def SOATAG_LOCAL_SDP(x)
 *  Get parsed local session description from soa session object.
 *
 * @par Used with
 *    soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    #sdp_session_t *
 *
 * @par Values
 *    pointer to #sdp_session_t.
 *
 * Corresponding tag taking reference parameter is SOATAG_LOCAL_SDP_REF()
 *
 * @sa soa_get_local_sdp(), SOATAG_LOCAL_SDP_STR(), SOATAG_USER_SDP(),
 * SOATAG_USER_SDP_STR().
 */
tag_typedef_t soatag_local_sdp = SDPTAG_TYPEDEF(local_sdp);

/**@def SOATAG_LOCAL_SDP_STR(x)
 * Get local session description as a string from soa session object.
 *
 * @par Used with
 *    soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 * char const *
 *
 * @par Values
 *  String containing SDP offer or answer.
 *
 * Corresponding tag taking reference parameter is SOATAG_LOCAL_SDP_STR_REF()..
 *
 * @sa soa_get_local_sdp(), SOATAG_LOCAL_SDP(),
 * SOATAG_USER_SDP(), SOATAG_USER_SDP_STR().
 */
tag_typedef_t soatag_local_sdp_str = STRTAG_TYPEDEF(local_sdp_str);

/**@def SOATAG_REMOTE_SDP(x)
 *  Pass parsed remote session description to soa session object.
 *
 * @par Used with
 *    soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    #sdp_session_t *
 *
 * @par Values
 *    pointer to #sdp_session_t.
 *
 * Corresponding tag taking reference parameter is SOATAG_REMOTE_SDP_REF()
 *
 * @sa soa_set_remote_sdp(), soa_get_remote_sdp(), SOATAG_REMOTE_SDP_STR(),
 * SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR().
 */
tag_typedef_t soatag_remote_sdp = SDPTAG_TYPEDEF(remote_sdp);

/**@def SOATAG_REMOTE_SDP_STR(x)
 *  Pass media description file name to the NUA stack.
 *
 * Pass name of media description file that contains media templates
 * (normally mss.sdp) to the NUA stack.
 *
 * @par Used with
 *    soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *    String containing SDP description received from remote end.
 *
 * Corresponding tag taking reference parameter is SOATAG_REMOTE_SDP_STR_REF()
 *
 * @sa soa_set_remote_sdp(), soa_get_remote_sdp(), SOATAG_REMOTE_SDP(),
 * SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR().
 */
tag_typedef_t soatag_remote_sdp_str = STRTAG_TYPEDEF(remote_sdp_str);

/**@def SOATAG_USER_SDP(x)
 *  Pass parsed user session description to soa session object.
 *
 * User SDP is used as basis for SDP Offer/Answer negotiation. It can be
 * very minimal, consisting just sdp_session_t structures, sdp_media_t
 * structures and sdp_rtpmap_t structures listing te supported media, used
 * RTP port number, and RTP payload descriptions of supported codecs.
 *
 * When generating the offer or answer the user SDP is augmented with the
 * required SDP lines (v=, o=, t=, c=, a=rtpmap, etc.) as required. The
 * complete offer or answer generated by @soa is passed in
 * SOATAG_LOCAL_SDP() (SOATAG_LOCAL_SDP_STR() contains same in text format).
 *
 * @par Used with
 *    soa_set_params(), soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    #sdp_session_t *
 *
 * @par Values
 *    pointer to #sdp_session_t.
 *
 * Corresponding tag taking reference parameter is SOATAG_USER_SDP_REF()
 *
 * @sa soa_set_user_sdp(), soa_get_user_sdp(), SOATAG_USER_SDP_STR(),
 * SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR().
 */
tag_typedef_t soatag_user_sdp = SDPTAG_TYPEDEF(user_sdp);

/**@def SOATAG_USER_SDP_STR(x)
 * Pass unparsed user session description to soa session object.
 *
 * User SDP is used as basis for SDP Offer/Answer negotiation. It can be
 * very minimal, listing just m= lines with the port numbers and RTP payload
 * numbers of supported codecs, like 
 * @code
 *   SOATAG_USER_SDP_STR("m=audio 5004 RTP/AVP 0 8")
 * @endcode
 * When generating the offer or answer the user SDP is augmented with the
 * required SDP lines (v=, o=, t=, c=, a=rtpmap, etc.) as required. The
 * complete offer or answer generated by @soa is passed in
 * SOATAG_LOCAL_SDP_STR() (SOATAG_LOCAL_SDP() contains session in parsed
 * format).
 *
 * @par Used with
 *    soa_set_params(), soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *    String containing minimal SDP description.
 *
 * Corresponding tag taking reference parameter is SOATAG_USER_SDP_STR_REF()
 *
 * @sa soa_set_user_sdp(), soa_get_user_sdp(), SOATAG_USER_SDP(),
 * SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR()
 */
tag_typedef_t soatag_user_sdp_str = STRTAG_TYPEDEF(user_sdp_str);

/**@def SOATAG_AF(x)
 *
 * Preferred address family for media.
 *
 * @par Used with
 *    soa_set_params(), soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    enum #soa_af {
 *      #SOA_AF_ANY,
 *      #SOA_AF_IP4_ONLY, #SOA_AF_IP6_ONLY,
 *      #SOA_AF_IP4_IP6,  #SOA_AF_IP6_IP4
 *    } 
 *
 * @par Values
 *    - #SOA_AF_ANY       (0) any address family (default)
 *    - #SOA_AF_IP4_ONLY  (1) only IP version 4
 *    - #SOA_AF_IP6_ONLY  (2) only IP version 6
 *    - #SOA_AF_IP4_IP6   (3) either IP version 4 or 6, version 4 preferred
 *    - #SOA_AF_IP6_IP4   (4) either IP version 4 or 6, version 6 preferred
 *
 * Corresponding tag taking reference parameter is SOATAG_AF_REF()
 *
 * @sa SOATAG_ADDRESS()
 */
tag_typedef_t soatag_af = INTTAG_TYPEDEF(af);


/**@def SOATAG_ADDRESS(x)
 *
 * Pass media address.
 *
 * @par Used with
 *    soa_set_params(), soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *    NUL-terminated C string containing a domain name,
 *    IPv4 address, or IPv6 address.
 *
 * Corresponding tag taking reference parameter is SOATAG_ADDRESS_REF()
 *
 * @sa SOATAG_AF()
 */
tag_typedef_t soatag_address = STRTAG_TYPEDEF(address);


/**@def SOATAG_RTP_SELECT(x)
 *
 * When generating answer or second offer, @soa can include all the supported
 * codecs, only one codec, or only the codecs supported by both ends in the
 * list of payload types on the m= line.
 *
 * @par Used with
 *    soa_set_params(), soa_get_params(), soa_get_paramlist() \n
 *
 * @par Parameter type
 *    enum { 
 *      #SOA_RTP_SELECT_SINGLE, #SOA_RTP_SELECT_COMMON, #SOA_RTP_SELECT_ALL
 *    } \n
 *    (int in range 0..2)
 *
 * @par Values
 *    - #SOA_RTP_SELECT_SINGLE (0) - select the best common codec
 *    - #SOA_RTP_SELECT_COMMON (1) - select all common codecs
 *    - #SOA_RTP_SELECT_ALL (2) - select all local codecs
 *
 * The default value is 0, only one RTP codec is selected. Note, however,
 * that if there is no common codec (no local codec is supported by remote
 * end), all the codecs are included in the list. In that case the media
 * line is rejected, too, unless SOATAG_RTP_MISMATCH(1) has been used.
 *
 * Corresponding tag taking a reference parameter is SOATAG_RTP_SELECT_REF().
 *
 * @sa SOATAG_RTP_MISMATCH(), SOATAG_RTP_SORT(), SOATAG_AUDIO_AUX()
 */
tag_typedef_t soatag_rtp_select = INTTAG_TYPEDEF(rtp_select);