nta_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 nta_tag.c
 * @brief Tags for Nokia SIP Transaction API
 *
 * @note This file is used to automatically generate 
 * nta_tag_ref.c and nta_tag_dll.c
 *
 * @author Pekka Pessi <[e-mail]>
 *
 * @date Created: Tue Jul 24 22:28:34 2001 ppessi
 */

#include "config.h"

#include <string.h>
#include <assert.h>

#define TAG_NAMESPACE "nta"

#include "sofia-sip/nta_tag.h"
#include <sofia-sip/su_tag_class.h>
#include <sofia-sip/sip_tag_class.h>
#include <sofia-sip/url_tag_class.h>

#include <sofia-sip/sip_protos.h>

tag_typedef_t ntatag_any = NSTAG_TYPEDEF(*);

/**@def NTATAG_MCLASS(x)
 *
 * Message class used by NTA. 
 *
 * The nta can use a custom or extended parser created with
 * msg_mclass_clone().
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    pointer to #msg_mclass_t.
 *
 * @par Values
 *    - custom or extended parser created with msg_mclass_clone()
 *    - NULL - use default parser
 *
 * @par Default Value
 *    - Value returned by sip_default_mclass()
 *
 * @sa NTATAG_SIPFLAGS()
 */
tag_typedef_t ntatag_mclass = PTRTAG_TYPEDEF(mclass);

/**@def NTATAG_BAD_REQ_MASK(x)
 *
 * Mask for bad request messages. 
 * 
 * If an incoming request has erroneous headers matching with the mask, nta
 * automatically returns a 400 Bad Message response to them. 
 *
 * If mask ~0U (all bits set) is specified, all requests with any bad header
 * are dropped. By default only the requests with bad headers essential for
 * request processing or proxying are dropped.
 * 
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - bitwise or of enum #sip_bad_mask values
 *
 * @par Default Value
 * - <code>sip_mask_response | sip_mask_ua | sip_mask_100rel | </code><br>
 *   <code>sip_mask_events | sip_mask_timer | sip_mask_publish</code>
 * The following headers are considered essential by default:
 * - @ref sip_request \"request line\"", @From, @To, @CSeq, @CallID,
 *   @ContentLength, @Via, @ContentType, @ContentDisposition,
 *   @ContentEncoding, @Supported, @Contact, @Require, @RecordRoute, @RAck,
 *   @RSeq, @Event, @Expires, @SubscriptionState, @SessionExpires,
 *   @MinSE, @SIPETag, and @SIPIfMatch.
 *  
 * @sa enum #sip_bad_mask, NTATAG_BAD_RESP_MASK()
 */
tag_typedef_t ntatag_bad_req_mask = UINTTAG_TYPEDEF(bad_req_mask);

/**@def NTATAG_BAD_RESP_MASK(x)
 *
 * Mask for bad response messages. 
 * 
 * If an incoming response has erroneous headers matching with the mask, nta
 * drops the response message. 
 *
 * If mask ~0U (all bits set) is specified, all responses with any bad header
 * are dropped. By default only the responses with bad headers essential for
 * response processing or proxying are dropped.
 * 
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - bitwise or of enum #sip_bad_mask values
 *
 * @sa enum #sip_bad_mask, NTATAG_BAD_REQ_MASK()
 *
 * @par Default Value
 * - <code>sip_mask_response | sip_mask_ua | sip_mask_100rel | </code><br>
 *   <code>sip_mask_events | sip_mask_timer | sip_mask_publish</code>
 * The following headers are considered essential by default:
 * - @ref sip_status \"status line\"", @From, @To, @CSeq, @CallID,
 *   @ContentLength, @Via, @ContentType, @ContentDisposition,
 *   @ContentEncoding, @Supported, @Contact, @Require, @RecordRoute, @RAck,
 *   @RSeq, @Event, @Expires, @SubscriptionState, @SessionExpires, 
 *   @MinSE, @SIPETag, and @SIPIfMatch.
 */
tag_typedef_t ntatag_bad_resp_mask = UINTTAG_TYPEDEF(bad_resp_mask);

/**@def NTATAG_DEFAULT_PROXY(x)
 *
 * URL for (default) proxy.
 *
 * The requests are sent towards the <i>default outbound proxy</i> regardless
 * the values of request-URI or @Route headers in the request. The URL of
 * the default proxy is not added to the request in the @Route header or in
 * the request-URI (against the recommendation of @RFC3261 section 8.1.2).
 *
 * The outbound proxy set by NTATAG_DEFAULT_PROXY() is used even if the
 * dialog had an established route set or registration provided User-Agent
 * with a @ServiceRoute set.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
 *
 * @par Parameter type
 *    Pointer to a url_t structure or a string containg a SIP or SIPS URI
 *
 * @par Values
 *    - Valid SIP or SIPS URI
 */
tag_typedef_t ntatag_default_proxy = URLTAG_TYPEDEF(default_proxy);

/**@def NTATAG_CONTACT(x)
 *
 * Contact used by NTA.
 */
tag_typedef_t ntatag_contact = SIPHDRTAG_NAMED_TYPEDEF(contact, contact);

/** @def NTATAG_TARGET(x)
 *
 * Dialog target (contact) used by NTA.
 */
tag_typedef_t ntatag_target = SIPHDRTAG_NAMED_TYPEDEF(target, contact);

/** @def NTATAG_ALIASES(x) 
 *
 * Aliases used by NTA. 
 * @deprecated
 */
tag_typedef_t ntatag_aliases = SIPHDRTAG_NAMED_TYPEDEF(aliases, contact);

/**@def NTATAG_METHOD(x)
 *
 * Method name.
 *
 * Create a dialogless #nta_leg_t object matching only requests with
 * the specified method.
 *
 * @par Used with
 *   nta_leg_tcreate()
 *
 * @par Parameter type
 *    String containing method name.
 *
 * @par Values
 *    - A SIP method name (e.g., "SUBSCRIBE").
 *
 * @par Default Value
 *    - None (i.e., all requests methods match with the leg)
 * 
 */
tag_typedef_t ntatag_method = STRTAG_TYPEDEF(method);

/**@def NTATAG_BRANCH_KEY(x)
 *
 * Branch ID to the topmost @Via header.
 *
 * The NTA generates a random branch ID for the topmost @Via header by default.
 * The application can the branch by itself, for intance, if it wants to
 * create a @RFC2543-era transaction.
 *
 * Note that according to @RFC3261 the branch ID must start with "z9hG4bK".
 *
 * @par Used with
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
 *
 * @par Parameter type
 *    string
 *
 * @par Value
 * - The "branch" ID to to insert into topmost @Via header of the 
 *   request to be sent
 *
 * @par Default Value
 *  - A token is generated, either by random when a client transaction is
 *    created or by hashing the headers and contents of the request when
 *    request is sent statelessly
 *
 * @sa @RFC3261 section 8.1.1.7
 */
tag_typedef_t ntatag_branch_key = STRTAG_TYPEDEF(branch_key);

/**@def NTATAG_ACK_BRANCH(x)
 *
 * Branch of the transaction to ACK. 
 *
 * When creating a ACK transaction, the application should provide the
 * branch parameter from the original transaction to the stack. The ACK
 * transaction object then receives all the retransmitted 2XX responses to
 * the original INVITE transaction.
 *
 * @par Used with
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate()
 *
 * @par Parameter type
 *    string
 *
 * @par Value
 *    - "branch" ID used to store the ACK transaction in the nta hash
 *      table for outgoing client transaction
 *
 * @par Default Value
 *  - The INVITE transaction is looked from the hash table using the @CallID,
 *    @CSeq, @From and @To tags and its branch ID is used
 */
tag_typedef_t ntatag_ack_branch = STRTAG_TYPEDEF(ack_branch);

/**@def NTATAG_COMP(x)
 *
 * Compression algorithm. 
 *
 * Set compression algorithm for request as described in @RFC3486.
 *
 * @note This tag is has no effect without a compression plugin.
 *
 * @par Used with
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
 *
 * @par
 * Note that NTATAG_COMP(NULL) can be used with nta_incoming_set_params()
 * and nta_incoming_treply(), too. It indicates that the response is sent
 * uncompressed, no matter what the client has in @a comp parameter of @Via
 * header.
 *
 * @par Parameter type
 *    string
 *
 * @par Values
 *    - name of the compression algorithm
 *
 * @par Default Value
 *    - "sigcomp"
 *
 * @sa @RFC3320, @RFC3486, TPTAG_COMPARTMENT(),
 * NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_AWARE(),
 * NTATAG_SIGCOMP_CLOSE(), NTATAG_SIGCOMP_OPTIONS()
 */
tag_typedef_t ntatag_comp = CSTRTAG_TYPEDEF(comp);

/**@def NTATAG_MSG(x)
 *
 * Pass a SIP message to treply()/tcreate() functions. 
 *
 * @par Used with
 *    nta_outgoing_tcreate(), nta_incoming_treply()
 *
 * @par Parameter type
 *    #msg_t
 *
 * @par Values
 * - A message object which will be completed, serialized and encoded.
 *   Note that the functions modify directly the message.
 *
 * @par Default Value
 * - A new  message object is created and populated by the function call.
 *
 * @sa msg_copy(), msg_dup(), msg_create(), sip_default_mclass()
 */
tag_typedef_t ntatag_msg = PTRTAG_TYPEDEF(msg);

/**@def NTATAG_TPORT(x)
 *
 * Pass a transport object. The transport object is used to send the request
 * or response message(s).
 *
 * @par Used with
 *    nta_outgoing_tcreate(), nta_outgoing_mcreate(), nta_outgoing_tcancel(), 
 *    nta_incoming_create(), nta_msg_tsend(), nta_msg_mreply()
 *
 * @par Parameter type
 *  - #tport_t
 *
 * @par Values
 * - A pointer to the transport object. Note that a new reference to the transport
 *   is created.
 *
 * @par Default Value
 * - The transport is selected by resolving the outbound URI (specified with
 *   NTATAG_DEFAULT_PROXY(), the topmost @Route URI or Request-URI.
 */
tag_typedef_t ntatag_tport = PTRTAG_TYPEDEF(tport);

/**@def NTATAG_SMIME(x)
 *
 * Provide S/MIME context to NTA. 
 *
 * @todo S/MIME is not implemented. 
 */
tag_typedef_t ntatag_smime = PTRTAG_TYPEDEF(smime);

/**@def NTATAG_REMOTE_CSEQ(x)
 *
 * Remote CSeq number.
 *
 * Specify remote command sequence number for a #nta_leg_t dialog object. If
 * an request is received matching with the dialog but with @CSeq number
 * less than the remote sequence number associated with the dialog, a <i>500
 * Internal Server Error</i> response is automatically returned to the client.
 *
 * @par Used with
 *   nta_leg_tcreate()
 *
 * @par Parameter type
 *   - uint32_t
 *
 * @par Values
 *    - Remote command sequence number 
 *
 * @par Default Value
 *    - Initially 0, then determined by the received requests
 *
 */
tag_typedef_t ntatag_remote_cseq = UINTTAG_TYPEDEF(remote_cseq);

/**@def NTATAG_MAXSIZE(x)
 *
 * Maximum size of incoming message. 
 *
 * If the size of an incoming request message would exceed the
 * given limit, the stack will automatically respond with <i>413 Request
 * Entity Too Large</i>.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    - #usize_t 
 *
 * @par Values
 *    - Maximum acceptable size of an incoming request message.
 *
 * @par Default Value
 *    - 2097152 (bytes or 2 megabytes)
 *
 * @sa msg_maxsize(), NTATAG_UDP_MTU()
 */
tag_typedef_t ntatag_maxsize = USIZETAG_TYPEDEF(maxsize);

/**@def NTATAG_MAX_PROCEEDING(x)
 *
 * Maximum size of proceeding queue. 
 *
 * If the size of the proceedng message queue would exceed the
 * given limit, the stack will automatically respond with <i>503 
 * Service Unavailable</i>.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    - #usize_t 
 *
 * @par Values
 *    - Maximum acceptable size of a queue (size_t).
 *
 */
tag_typedef_t ntatag_max_proceeding = USIZETAG_TYPEDEF(max_proceeding);

/**@def NTATAG_UDP_MTU(x)
 *
 * Maximum size of outgoing UDP request. 
 *
 * The maximum UDP request size is used to control use of UDP with overtly
 * large messages. The IETF requires that the SIP requests over 1300 bytes
 * are sent over congestion-controlled transport such as TCP. If a SIP
 * message size exceeds the UDP MTU, the TCP is tried instead of UDP. (If
 * the TCP connection is refused, the stack reverts back to UDP).
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    - unsigned
 *
 * @par Values
 *    - Maximum size of an outgoing UDP request
 *
 * @par Default Value
 *    - 1300 (bytes)
 *
 * @sa @RFC3261 section 18.1.1, NTATAG_MAXSIZE()
 */
tag_typedef_t ntatag_udp_mtu = UINTTAG_TYPEDEF(udp_mtu);

/**@def NTATAG_MAX_FORWARDS(x)
 *
 * Default value for @MaxForwards header. 
 *
 * The default value of @MaxForwards header added to the requests. The
 * initial value recommended by @RFC3261 is 70, but usually SIP proxies use
 * much lower default value, such as 24.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned
 *
 * @par Values
 *    - Default value added to the @MaxForwards header in the sent requests
 *
 * @par Default Value