nta_tag.c

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

 *    - 70 (hops)
 *
 * @since New in @VERSION_1_12_2.
 */
tag_typedef_t ntatag_max_forwards = UINTTAG_TYPEDEF(max_forwards);

/**@def NTATAG_SIP_T1(x)
 *
 * Initial retransmission interval (in milliseconds) 
 *
 * Set the T1 retransmission interval used by the SIP transaction engine. The
 * T1 is the initial duration used by request retransmission timers A and E
 * (UDP) as well as response retransmission timer G.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - Value of SIP T1 in milliseconds 
 *
 * @par Default Value
 *    - #NTA_SIP_T1 or 500 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T1, NTATAG_SIP_T1X4(), NTATAG_SIP_T1(), NTATAG_SIP_T4()
 */
tag_typedef_t ntatag_sip_t1 = UINTTAG_TYPEDEF(sip_t1);

/**@def NTATAG_SIP_T1X64(x)
 *
 * Transaction timeout (defaults to T1 * 64). 
 *
 * Set the T1x64  timeout value used by the SIP transaction engine. The T1x64 is
 * duration used for timers B, F, H, and J (UDP) by the SIP transaction engine. 
 * The timeout value T1x64 can be adjusted separately from the initial
 * retransmission interval T1, which is set with NTATAG_SIP_T1().
 * 
 * The default value for T1x64 is 64 times value of T1, or 32000 milliseconds.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - Value of T1x64 in milliseconds
 *
 * @par Default Value
 *    - 64 * #NTA_SIP_T1 or 32000 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T1, NTATAG_SIP_T1(), NTATAG_SIP_T2(), NTATAG_SIP_T4()
 *
 */
tag_typedef_t ntatag_sip_t1x64 = UINTTAG_TYPEDEF(sip_t1x64);

/**@def NTATAG_SIP_T2(x)
 *
 * Maximum retransmission interval (in milliseconds) 
 *
 * Set the maximum retransmission interval used by the SIP transaction
 * engine. The T2 is the maximum duration used for the timers E (UDP) and G
 * by the SIP transaction engine. Note that the timer A is not capped by T2. 
 * Retransmission interval of INVITE requests grows exponentially until the
 * timer B fires.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - Value of SIP T2 in milliseconds 
 *
 * @par Default Value
 *    - #NTA_SIP_T2 or 4000 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T2, NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T4()
 */
tag_typedef_t ntatag_sip_t2 = UINTTAG_TYPEDEF(sip_t2);

/**@def NTATAG_SIP_T4(x)
 *
 * Transaction lifetime (in milliseconds) 
 *
 * Set the lifetime for completed transactions used by the SIP transaction
 * engine. A completed transaction is kept around for the duration of T4 in
 * order to catch late responses. The T4 is the maximum duration for the
 * messages to stay in the network and the duration of SIP timer K.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - Value of SIP T4 in milliseconds
 *
 * @par Default Value
 *    - #NTA_SIP_T4 or 4000 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T4, NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T2()
 */
tag_typedef_t ntatag_sip_t4 = UINTTAG_TYPEDEF(sip_t4);

/**@def NTATAG_PROGRESS(x)
 *
 * Progress timer for User-Agents (interval for retranmitting 1XXs).
 *
 * The UAS should retransmit preliminary responses to the INVITE
 * transactions every minute in order to re-set the timer C within the
 * intermediate proxies.
 *
 * The default value for the progress timer is 60000.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    Value of progress timer in milliseconds.
 *
 * @par Default Value
 *   - 90000 (milliseconds, 1.5 minutes)
 *
 * @sa @RFC3261 sections 13.3.1.1, 16.7 and 16.8, NTATAG_TIMER_C(),
 * NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T2(), NTATAG_SIP_T4()
 */
tag_typedef_t ntatag_progress = UINTTAG_TYPEDEF(progress);

/**@def NTATAG_TIMER_C(x)
 *
 * Value for timer C in milliseconds.
 *
 * By default the INVITE transaction will not timeout after a preliminary
 * response has been received. However, an intermediate proxy can timeout
 * the transaction using timer C. Timer C is reset every time a response
 * belonging to the transaction is received.
 *
 * The default value for the timer C is 185000 milliseconds (3 minutes and 5
 * seconds). By default, timer C is not run on user agents (if NTATAG_UA(1)
 * without NTATAG_TIMER_C() is given).
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    Value of SIP timer C in milliseconds. The default value is used
 *    instead if NTATAG_TIMER_C(0) is given.
 *
 * @par Default Value
 *   - 180000 (milliseconds, 3 minutes)
 *
 * @sa @RFC3261 sections 13.3.1.1, 16.7 and 16.8,
 * NTATAG_UA(1), NTATAG_TIMER_C(),
 * NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T2(), NTATAG_SIP_T4()
 *
 * @NEW_1_12_7.
 */
tag_typedef_t ntatag_timer_c = UINTTAG_TYPEDEF(timer_c);

/**@def NTATAG_GRAYLIST(x)
 *
 * Avoid failed servers.
 *
 * The NTATAG_GRAYLIST() provides the time that the servers are avoided
 * after a request sent to them has been failed. Avoiding means that if a
 * domain provides multiple servers, the failed servers are tried last.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *     unsigned int
 *
 * @par Values
 *    - Number of seconds that server is kept in graylist, from 0 to 86400.
 *
 * @par Default Value
 *    - 600 (graylist server for 10 minutes)
 *
 * @sa NTATAG_BLACKLIST(), NTATAG_TIMEOUT_408()
 */
tag_typedef_t ntatag_graylist = UINTTAG_TYPEDEF(graylist);

/**@def NTATAG_BLACKLIST(x)
 *
 * Add Retry-After header to error responses returned to application.
 *
 * The NTATAG_BLACKLIST() provides a default value for @RetryAfter header
 * added to the internally generated responses such as <i>503 DNS Error</i>
 * or <i>408 Timeout</i>. The idea is that the application can retain its
 * current state and retry the operation after a while.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *     unsigned int
 *
 * @par Values
 *    - Value of @a delta-seconds in @RetryAfter header, from 0 to 86400
 *
 * @par Default Value
 *    - 0 (no @RetryAfter header is included)
 *
 * @sa NTATAG_TIMEOUT_408()
 */
tag_typedef_t ntatag_blacklist = UINTTAG_TYPEDEF(blacklist);

/**@def NTATAG_DEBUG_DROP_PROB(x)
 *
 * Packet drop probability for debugging. 
 *
 * The packet drop probability parameter is useful mainly for debugging
 * purposes. The stack drops an incoming message received over an unreliable
 * transport (such as UDP) with the given probability. The range is in 0 .. 
 * 1000, 500 means p=0.5.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned integer
 *
 * @par Values
 *    - Valid values are in range 0 ... 1000
 *    - Probablity to drop a given message is value / 1000.
 *
 * @par Default Value
 *    - 0 (no packets are dropped)
 *
 * @sa TPTAG_DEBUG_DROP()
 */
tag_typedef_t ntatag_debug_drop_prob = UINTTAG_TYPEDEF(debug_drop_prob);

/**@def NTATAG_SIGCOMP_OPTIONS(x)
 *
 * Semicolon-separated SigComp options.
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
 *    nta_agent_add_tport()
 *
 * @par Parameter type
 *    string 
 *
 * @par Values
 *    - semicolon-separated parameter-value pairs, passed to the SigComp plugin
 *
 * @sa NTATAG_COMP(), NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_AWARE(),
 * NTATAG_SIGCOMP_CLOSE(), @RFC3320
 */
tag_typedef_t ntatag_sigcomp_options = STRTAG_TYPEDEF(sigcomp_options);

/**@def NTATAG_SIGCOMP_CLOSE(x)
 *
 * Close SigComp compartment after completing transaction.
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
 *    nta_incoming_set_params(), nta_incoming_treply()
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tmcreate(), nta_outgoing_tcancel(),
 *    nta_outgoing_prack(), nta_msg_tsend(), nta_msg_treply()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - application takes care of compartment management
 *    - false - stack manages compartments
 *
 * @sa NTATAG_COMP(), TPTAG_COMPARTMENT(),
 * NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_AWARE(),
 * NTATAG_SIGCOMP_OPTIONS(), @RFC3320
 */
tag_typedef_t ntatag_sigcomp_close = BOOLTAG_TYPEDEF(sigcomp_close);

/**@def NTATAG_SIGCOMP_AWARE(x)
 *
 * Indicate that the application is SigComp-aware. 
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - application takes care of compartment management
 *    - false - stack manages compartments
 *
 * @sa NTATAG_COMP(), NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_CLOSE(),
 * NTATAG_SIGCOMP_OPTIONS(), @RFC3320
 */
tag_typedef_t ntatag_sigcomp_aware = BOOLTAG_TYPEDEF(sigcomp_aware);

/**@def NTATAG_SIGCOMP_ALGORITHM(x)
 *
 * Specify SigComp algorithm.  
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
 *    nta_agent_add_tport()
 *
 * @par Parameter type
 *    string 
 *
 * @par Values
 *    - opaque string passed to the SigComp plugin
 *
 * @sa NTATAG_COMP(), NTATAG_SIGCOMP_AWARE(), NTATAG_SIGCOMP_CLOSE(),
 * NTATAG_SIGCOMP_OPTIONS(), @RFC3320
 */
tag_typedef_t ntatag_sigcomp_algorithm = STRTAG_TYPEDEF(sigcomp_algorithm);

/**@def NTATAG_UA(x)
 *
 * If true, NTA acts as User Agent Server or Client by default.
 *
 * When acting as an UA, the NTA stack will
 * - respond with 481 to a PRACK request with no matching "100rel" response
 * - check for out-of-order CSeq headers for each #nta_leg_t dialog object
 * - if NTATAG_MERGE_482(1) is also used, return <i>482 Request Merged</i> to
 *   a duplicate request with same @CallID, @CSeq, @From tag but different
 *   topmost @Via header (see @RFC3261 section 8.2.2.2 Merged Requests)
 * - silently discard duplicate final responses to INVITE
 * - retransmit preliminary responses (101..199) to INVITE request in regular
 *   intervals ("timer N2")
 * - retransmit 2XX response to INVITE request with exponential intervals 
 * - handle ACK sent in 2XX response to an INVITE using the
 *   #nta_ack_cancel_f callback bound to #nta_incoming_t with
 *   nta_incoming_bind()
 * - not use timer C unless its value has been explicitly set
 *
 * @note This NUTAG_UA(1) is set internally by nua_create()
 *
 * @par Used with
 *    nta_agent_create() \n
 *    nta_agent_set_params() \n
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - act as an UA 
 *    - false - act as an proxy 
 *
 * @par Default Value
 *    - 0 (false)
 *    
 * @sa NTATAG_MERGE_482()
 */
tag_typedef_t ntatag_ua = BOOLTAG_TYPEDEF(ua);

/**@def NTATAG_STATELESS(x)
 *
 * Enable stateless processing.
 *
 * @par Server side
 * The incoming requests are processed statefully if there is a default leg
 * (created with nta_leg_default()). This option is provided for proxies or
 * other server elements that process requests statelessly.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Values
 *    - true - do not pass incoming requests to default leg
 *    - false - pass incoming requests to default leg, if it exists
 *
 * @par Default Value
 *    - 0 (false,  pass incoming requests to default leg)
 *
 * @par Client side
 * The outgoing requests can be sent statelessly, too, if the
 * NTATAG_STATELESS(1) is included in the tag list of nta_outgoing_tcreate().
 *
 * @par Used with
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - create only a transient #nta_outgoing_t transaction object
 *    - false - create an ordinary client transaction object
 *
 * @par Default Value
 *    - 0 (false, create client transaction)
 *
 * @sa NTATAG_IS_UA(), nta_incoming_default(), nta_outgoing_default(),
 * nta_leg_default()
 */
tag_typedef_t ntatag_stateless = BOOLTAG_TYPEDEF(stateless);

/**@def NTATAG_USER_VIA(x)
 *
 * Allow application to insert Via headers.
 *
 * @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
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - do not add @Via header to the request (if it has one)
 *    - false - always add a @Via header
 *
 * @par Default Value
 *    - 0 (false, always add a @Via header)
 *
 * @sa NTATAG_BRANCH(), NTATAG_TPORT()
 */
tag_typedef_t ntatag_user_via = BOOLTAG_TYPEDEF(user_via);

/**@def NTATAG_PASS_100(x)
 *
 * Pass "<i>100 Trying</i>" provisional answers to the application.
 *
 * By default, the stack silently processes the <i>100 Trying</i> responses
 * from the server. Usually the <i>100 Trying</i> responses are not
 * important to the application but rather sent by the outgoing proxy
 * immediately after it has received the request. However, the application
 * can ask nta for them by setting NTATAG_PASS_100(1) if, for instance, the
 * <i>100 Trying</i> responses are needed for user feedback.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),