nua_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 nua_tag.c  Tags and tag lists for NUA
 *
 * @author Pekka Pessi <[e-mail]>
 * @author Martti Mela <[e-mail]>
 *
 * @date Created: Wed Feb 21 10:13:29 2001 ppessi
 */

#include "config.h"

#define TAG_NAMESPACE "nua"

#include "sofia-sip/nua_tag.h"

#include <sofia-sip/msg_header.h>
#include <sofia-sip/su_tag_class.h>
#include <sofia-sip/url_tag_class.h>
#include <sofia-sip/sip_tag_class.h>
#include <sofia-sip/sip_hclasses.h>

/** @page nua_api_overview NUA API Overview
 *
 * This page shortly overviews the NUA API: different functions, tags, and
 * where and how they affect the working of NUA engine.
 *
 * The application and the NUA engine can pass various parameters between
 * them using tagged arguments. Tagged arguments can be used like named
 * arguments in higher-lever language.
 *
 * @par NUA Agent
 *
 * The NUA agent object is created with nua_create(). The nua_create() also
 * creates the transports and binds the transport sockets used by the SIP
 * stack.
 *
 * The special tags controlling the transports are
 * - NUTAG_URL(), NUTAG_SIPS_URL(),  NUTAG_CERTIFICATE_DIR(), NUTAG_SIP_PARSER()
 *
 * See nta_agent_add_tport() for discussion about magic URIs used to
 * initialize transports.
 *
 * The agent-wide parameter can be later modified or obtained with
 * nua_set_params() and nua_get_params(), respectively.
 *
 * The #su_root_t mainloop integration uses
 * - su_root_create(), su_root_threading(),
 *   su_root_poll(), su_root_run(), su_root_break()
 *
 * @par NUA Handles
 * - nua_handle(), nua_get_hparams(), nua_set_hparams()
 * - nua_handle_home(), nua_handle_has_invite(), nua_handle_has_subscribe(),
 *   nua_handle_has_register(), nua_handle_has_active_call(),
 *   nua_handle_has_call_on_hold(), nua_handle_has_events(),
 *   nua_handle_has_registrations(), nua_handle_remote(), and
 *   nua_handle_local().
 * - Settings:
 *   See nua_set_hparams(). There are a few "sticky" headers that are used
 *   on subsequent requests if given on any handle-specific call:
 *   - @Contact, @UserAgent, @Supported, @Allow, @Organization
 *
 * @par Client Generating SIP Requests
 * - nua_register(), nua_unregister(), nua_invite(), nua_cancel(),
 *   nua_ack(), nua_bye(), nua_options(), nua_refer(), nua_publish(),
 *   nua_unpublish(), nua_prack(), nua_info(), nua_update(), nua_message(),
 *   nua_subscribe(), nua_unsubscribe(), nua_notify(), nua_method()
 * - NUTAG_URL()
 *  Settings:
 * - NUTAG_RETRY_COUNT(), NUTAG_PROXY(),
 *   NUTAG_INITIAL_ROUTE() and NUTAG_INITIAL_ROUTE_STR()
 * - NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
 * - NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR()
 * - NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR()
 * - SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR()
 *
 * @par Client Authenticating Requests
 * - nua_authenticate(), #nua_r_authenticate
 * - NUTAG_AUTH(), NUTAG_AUTH_CACHE()
 *
 * @par Server Processing Received SIP Requests
 * - nua_respond(), NUTAG_WITH_THIS(), NUTAG_WITH_SAVED(), NUTAG_WITH()
 * - #nua_i_invite, #nua_i_cancel, #nua_i_ack, #nua_i_bye,
 *   #nua_i_options, #nua_i_refer, #nua_i_publish, #nua_i_prack,
 *   #nua_i_info, #nua_i_update, #nua_i_message, #nua_i_subscribe,
 *   #nua_i_notify, #nua_i_method, #nua_i_register
 *  Settings:
 * - NUTAG_APPL_METHOD(), NUTAG_PROXY()
 * - NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
 * - NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR()
 *
 * @par Registrations and Contact Header Generation
 * - nua_register(), #nua_r_register(), #nua_i_outbound,
 *   nua_unregister(), and #nua_r_unregister
 * Settings:
 * - NUTAG_CALLEE_CAPS()
 * - NUTAG_DETECT_NETWORK_UPDATES()
 * - NUTAG_INSTANCE()
 * - NUTAG_KEEPALIVE()
 * - NUTAG_KEEPALIVE_STREAM()
 * - NUTAG_M_DISPLAY()
 * - NUTAG_M_FEATURES()
 * - NUTAG_M_PARAMS()
 * - NUTAG_M_USERNAME()
 * - NUTAG_OUTBOUND()
 * - NUTAG_PATH_ENABLE()
 * - NUTAG_SERVICE_ROUTE_ENABLE()
 * Specifications:
 * - @RFC3261 section 10, @RFC3327, @RFC3608, @RFC3680, @RFC3840,
 *   draft-ietf-sip-outbound, draft-ietf-sip-gruu-14
 *
 * @par INVITE Sessions and Call Model
 * - nua_invite(), #nua_r_invite, #nua_i_invite
 * - nua_handle_has_active_call(), nua_handle_has_call_on_hold(),
 *   nua_handle_has_invite()
 * - nua_cancel(), #nua_r_cancel, #nua_i_cancel
 * - nua_ack(), #nua_i_ack
 * - nua_bye(), #nua_r_bye, #nua_i_bye
 * - #nua_i_state, NUTAG_CALLSTATE(),
 *   NUTAG_OFFER_SENT(), NUTAG_OFFER_RECV(), NUTAG_ANSWER_RECV(), and
 *   NUTAG_ANSWER_SENT(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(),
 *   SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR()
 *  Settings:
 * - NUTAG_AUTOACK(), NUTAG_AUTOALERT(), NUTAG_AUTOANSWER(),
 *   NUTAG_ENABLEINVITE(), NUTAG_INVITE_TIMER(), NUTAG_MEDIA_ENABLE(),
 *   SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_CAPS_SDP(),
 *   SOATAG_CAPS_SDP_STR()
 * Specifications:
 * - @RFC3261, @RFC3264
 *
 * @par In-Session Information requests
 * - nua_info() #nua_r_info, #nua_i_info
 * Settings:
 * - NUTAG_ALLOW("INFO"), NUTAG_APPL_METHOD("INFO")
 *
 * @par SDP Processing
 * - #nua_i_state, SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO(),
 *   SOATAG_ACTIVE_IMAGE(), SOATAG_ACTIVE_CHAT(),
 *   SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(),
 *   SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR()
 * Settings:
 * - NUTAG_MEDIA_ENABLE(), NUTAG_SOA_NAME(), NUTAG_EARLY_ANSWER(),
 *   SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_CAPS_SDP(),
 *   SOATAG_CAPS_SDP_STR()
 * Specifications:
 * - @RFC3264
 *
 * @par Call Model Extensions ("100rel" and "precondition")
 * Early
 * - nua_prack(), #nua_r_prack, #nua_i_prack
 * - nua_update() #nua_r_update, #nua_i_update
 * Settings:
 * - NUTAG_EARLY_MEDIA(), NUTAG_ONLY183_100REL()
 * - "100rel" or "precondition" in NUTAG_SUPPORTED()/SIPTAG_SUPPORTED()
 * Specifications:
 * - @RFC3262, @RFC3311, @RFC3312
 *
 * @par SIP Session Timers ("timer")
 * Periodic refresh of SIP Session initiated with INVITE with re-INVITE or
 * UPDATE requests.
 * Settings:
 * - NUTAG_MIN_SE(), NUTAG_SESSION_REFRESHER(),
 *   NUTAG_SESSION_TIMER(), NUTAG_UPDATE_REFRESH()
 * - "timer" in NUTAG_SUPPORTED()/SIPTAG_SUPPORTED()
 * Specifications:
 * - @RFC4028
 *
 * @par Caller Preferences and Callee Caps
 * - Caller preferences in @AcceptContact header in a INVITE requests
 * - Callee caps contained in @Contact header in a REGISTER request
 * Settings:
 * - NUTAG_CALLEE_CAPS(), NUTAG_MEDIA_FEATURES(),
 *   NUTAG_M_FEATURES()
 * Specifications:
 * - @RFC3840, @RFC3841
 *
 * @par Instant Messaging
 * - nua_message(), #nua_r_message, #nua_i_message
 * Settings:
 * - NUTAG_APPL_METHOD("MESSAGE"),
 *   NUTAG_ENABLEMESSAGE(), NUTAG_ENABLEMESSENGER()
 * Specifications:
 * - @RFC3428
 *
 * @par Call Transfer
 * - nua_refer(), #nua_r_refer, #nua_i_notify, SIPTAG_EVENT(),
 *   @ReferTo, SIPTAG_REFER_TO(), @ReferredBy, SIPTAG_REFERRED_BY(),
 *   nua_handle_make_replaces(), @Replaces, SIPTAG_REPLACES(),
 *   @ReferSub, SIPTAG_REFER_SUB()
 * - #nua_i_refer, nua_notify(), #nua_r_notify,
 *   nua_handle_by_replaces()
 * - nua_invite() with NUTAG_NOTIFY_REFER() and NUTAG_REFER_EVENT()
 * Settings:
 * - NUTAG_REFER_EXPIRES(), NUTAG_REFER_WITH_ID()
 * Specifications:
 * - @RFC3515 (@ReferTo), @RFC3892 (@ReferredBy), @RFC3891 (@Replaces),
 *   @RFC4488, @ReferSub
 *
 * @par Internal SIP Event Server
 * - nua_notifier(), #nua_r_notifier, #nua_i_subscription,
 *   nua_authorize(), #nua_r_authorize, nua_terminate(), #nua_r_terminate
 * - SIPTAG_EVENT(), SIPTAG_CONTENT_TYPE(), SIPTAG_PAYLOAD(),
 *   NUTAG_SUBSTATE()
 * @par Settings
 * - NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and
 *                          SIPTAG_ALLOW_EVENTS_STR()
 * - NUTAG_MAX_SUBSCRIPTIONS()
 * - NUTAG_SUBSTATE(), NUTAG_SUB_EXPIRES()
 * @par Specifications
 * - @RFC3265
 *
 * @par SIP Event Subscriber
 * - nua_subscribe(), #nua_r_subscribe, #nua_i_notify, NUTAG_SUBSTATE(),
 *   SIPTAG_EVENT(), SIPTAG_EXPIRES()
 * - nua_unsubscribe(), #nua_r_unsubscribe()
 * @par Specifications
 * - @RFC3265
 *
 * @par SIP Event Notifier
 * - #nua_i_subscribe(), nua_notify(), #nua_r_notify,
 *   NUTAG_SUBSTATE(), NUTAG_SUB_EXPIRES(), SIPTAG_EVENT()
 * Settings:
 * - NUTAG_SUB_EXPIRES()
 * - NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and
 *                          SIPTAG_ALLOW_EVENTS_STR()
 * - NUTAG_ALLOW("SUBSCRIBE"), NUTAG_APPL_METHOD("SUBSCRIBE")
 * @par Specifications
 * - @RFC3265
 *
 * @par SIP Event Publisher
 * - nua_publish(), #nua_r_publish(), nua_unpublish(), nua_r_unpublish()
 * - @SIPETag, SIPTAG_ETAG(), @SIPIfMatch, SIPTAG_IF_MATCH()
 * @par Specifications
 * - @RFC3903
 *
 * @par SIP Event State Compositor (PUBLISH Server)
 * - #nua_i_publish, @SIPETag, @SIPIfMatch
 * @par Settings
 * - NUTAG_ALLOW("PUBLISH"), NUTAG_APPL_METHOD("PUBLISH")
 * @par Specifications
 * - @RFC3903
 *
 * @par Non-Standard Extension Methods
 * - nua_method(), NUTAG_METHOD(), #nua_r_method, NUTAG_DIALOG()
 * - #nua_i_method, nua_respond()
 * Settings:
 * - NUTAG_ALLOW(x), NUTAG_APPL_METHOD(x)
 *
 * @par Server Shutdown
 * - nua_shutdown(), NUTAG_SHUTDOWN_EVENTS(), nua_destroy().
 */

/* @par S/MIME
 * - NUTAG_SMIME_ENABLE()
 * - NUTAG_SMIME_KEY_ENCRYPTION()
 * - NUTAG_SMIME_MESSAGE_DIGEST()
 * - NUTAG_SMIME_MESSAGE_ENCRYPTION()
 * - NUTAG_SMIME_OPT()
 * - NUTAG_SMIME_PROTECTION_MODE()
 * - NUTAG_SMIME_SIGNATURE()
 */

tag_typedef_t nutag_any = NSTAG_TYPEDEF(*);

/**@def NUTAG_URL()
 *
 * URL address from application to NUA
 *
 * @par Used with
 *    any function that create SIP request or nua_handle() \n
 *    nua_create() \n
 *    nua_set_params() \n
 *    nua_get_params() \n
 *
 * @par Parameter type
 *    char const *   or   url_t *  or url_string_t *
 *
 * @par Values
 *    #url_string_t, which is either a pointer to #url_t or NULL terminated
 *    character string representing URL \n
 *
 * For normal nua calls, this tag is used as request target, which is usually
 * stored as request-URI.
 *
 * It is used to set stack's own address with nua_create(), nua_set_params()
 * and nua_get_params(). It can be specified multiple times when used with
 * nua_create().
 *
 * @sa SIPTAG_TO()
 *
 * Corresponding tag taking reference parameter is NUTAG_URL_REF()
 */
tag_typedef_t nutag_url = URLTAG_TYPEDEF(url);


/**@def NUTAG_METHOD(x)
 *
 * Extension method name.
 *
 * Specify extension method name with nua_method() function.
 *
 * @par Used with
 *    nua_method() \n
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *    Extension method name (e.g., "SERVICE")
 *
 * Corresponding tag taking reference parameter is NUTAG_METHOD_REF()
 *
 * @sa nua_method(), SIP_METHOD_UNKNOWN()
 *
 * @since New in @VERSION_1_12_4.
 */
tag_typedef_t nutag_method = STRTAG_TYPEDEF(method);

/**@def NUTAG_METHOD_REF(x) 
 * Reference tag for NUTAG_METHOD().
 */


/*#@def NUTAG_UICC(x)
 *
 * Intentionally undocumented.
 */
tag_typedef_t nutag_uicc = STRTAG_TYPEDEF(uicc);

/*#@def NUTAG_UICC_REF(x) 
 * Reference tag for NUTAG_UICC().
 */


/**@def NUTAG_MEDIA_FEATURES()
 *
 * Add media tags from our offer to Accept-Contact headers.
 *
 * Automatically generate @AcceptContact headers for caller
 * preference processing according to the media capabilities in @a soa.
 *
 * @par Used with
 * - nua_create(), nua_set_params(), nua_get_params()
 * - nua_handle(), nua_set_hparams(), nua_get_hparams()
 * - nua_invite()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   Do not add @AcceptContact \n
 *    @c !=0 Add @AcceptContact with media tags
 *
 * Corresponding tag taking reference parameter is NUTAG_MEDIA_FEATURES_REF()
 *
 * @sa nua_invite(), @AcceptContact, @RFC3841, @RFC3840, SOATAG_USER_SDP(),
 * SIPTAG_ACCEPT_CONTACT(), NUTAG_CALLEE_CAPS()
 */
tag_typedef_t nutag_media_features = BOOLTAG_TYPEDEF(media_features);

/**@def NUTAG_MEDIA_FEATURES_REF(x) 
 * Reference tag for NUTAG_MEDIA_FEATURES().
 */


/**@def NUTAG_CALLEE_CAPS(x) 
 * 
 * Add methods parameter and media feature parameter to the @Contact headers
 * generated for REGISTER request.
 *
 * @par Used with
 * - nua_create(), nua_set_params(), nua_get_params()
 * - nua_handle(), nua_set_hparams(), nua_get_hparams()
 * - nua_register()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   Do not include methods and media feature paramete \n
 *    @c !=0 Include media tags in 
 *
 * Corresponding tag taking reference parameter is NUTAG_MEDIA_FEATURES_REF().
 *
 * @sa nua_register(), @Contact, NUTAG_M_FEATURES(), @RFC3840, @RFC3841,
 * SOATAG_USER_SDP(), NUTAG_MEDIA_FEATURES()
 */
tag_typedef_t nutag_callee_caps = BOOLTAG_TYPEDEF(callee_caps);

/**@def NUTAG_CALLEE_CAPS_REF(x) 
 * Reference tag for NUTAG_CALLEE_CAPS().
 */


/**@def NUTAG_EARLY_MEDIA(x)
 *
 * Establish early media session using 100rel, 183 responses and PRACK.
 *
 * @par Used with
 * - nua_create(), nua_set_params(), nua_get_params()
 * - nua_handle(), nua_set_hparams(), nua_get_hparams()
 * - nua_invite(), nua_respond()
 *
 * @par Parameter type
 *    int (boolean)
 *
 * @par Values
 *    @c 0   False - do not try to use early media \n
 *    @c !=0 True - try to use early media
 *
 * @sa NUTAG_EARLY_ANSWER()
 *
 * Corresponding tag taking reference parameter is NUTAG_EARLY_MEDIA_REF().
 */
tag_typedef_t nutag_early_media = BOOLTAG_TYPEDEF(early_media);

/**@def NUTAG_EARLY_MEDIA_REF(x) 
 * Reference tag for NUTAG_EARLY_MEDIA().
 */


/**@def NUTAG_ONLY183_100REL(x)
 *
 * Require 100rel extension and PRACK only with 183 response.
 *
 * If this parameter is set, stack includes feature tag "100rel" in the
 * @Require header only with 183: otherwise, all 1XX responses (except
 * <i>100 Trying</i>) require 100rel.
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params() \n
 *    nua_handle() \n
 *    nua_set_hparams() \n
 *    nua_get_hparams() \n
 *    nua_invite() \n
 *    nua_respond()
 *
 * @par Parameter type
 *    int (boolean)
 *
 * @par Values
 *    @c 0   False \n
 *    @c !=0 True
 *
 * Corresponding tag taking reference parameter is NUTAG_ONLY183_100REL_REF().
 */
tag_typedef_t nutag_only183_100rel = BOOLTAG_TYPEDEF(only183_100rel);

/**@def NUTAG_ONLY183_100REL_REF(x) 
 * Reference tag for NUTAG_ONLY183_100REL().
 */