nta_tag.c

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

 *    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 - pass <i>100 Trying</i> to application
 *    - false - silently process <i>100 Trying</i> responses
 *
 * @par Default Value
 *    - 0 (false, save application from seeing 100 Trying)
 *
 * @sa NTATAG_EXTRA_100(), NTATAG_DEFAULT_PROXY()
 */
tag_typedef_t ntatag_pass_100 = BOOLTAG_TYPEDEF(pass_100);

/**@def NTATAG_EXTRA_100(x)
 *
 * Respond with "100 Trying" if application has not responded.
 *
 * As per recommended by @RFC4320, the stack can generate a 100 Trying
 * response to the non-INVITE requests if the application has not responded
 * to a request within half of the SIP T2 (the default value for T2 is 4000
 * milliseconds, so the extra <i>100 Trying</i> would be sent after 2 seconds).
 *
 * @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 - send extra 100 Trying if application does not respond
 *    - false - do not send 100 Trying
 *
 * @par Default Value
 *    - 0 (false, do not respond with 100 Trying to retransmissions)

 * @sa @RFC4320, NTATAG_PASS_408(), NTATAG_TIMEOUT_408()
 */
tag_typedef_t ntatag_extra_100 = BOOLTAG_TYPEDEF(extra_100);

/**@def NTATAG_TIMEOUT_408(x)
 *
 * Generate "408 Request Timeout" response when request times out. 
 *
 * This tag is used to prevent stack from generating extra 408 response
 * messages to non-INVITE requests upon timeout. As per recommended by
 * @RFC4320, the <i>408 Request Timeout</i> responses to non-INVITE
 * transaction are not sent over the network to the client by default. The
 * application can ask stack to pass the 408 responses with
 * NTATAG_PASS_408(1).
 *
 * @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 - generate 408 response
 *    - false - invoke #nta_response_f callback with NULL sip pointer
 *              when a non-INVITE transaction times out
 *
 * @sa @RFC4320, NTATAG_PASS_408(), NTATAG_EXTRA_100(),
 */
tag_typedef_t ntatag_timeout_408 = BOOLTAG_TYPEDEF(timeout_408);

/**@def NTATAG_PASS_408(x)
 *
 * Pass "408 Request Timeout" responses to the client. 
 *
 * As per recommended by @RFC4320, the <i>408 Request Timeout</i> responses
 * to non-INVITE transaction are not sent over the network to the client by
 * default. The application can ask stack to pass the 408 responses with
 * NTATAG_PASS_408(1). 
 *
 * Note that unlike NTATAG_PASS_100(), this tags changes the way server side
 * works.
 *
 * @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 - pass superfluous 408 responses 
 *    - false - discard superfluous 408 responses
 *
 * @sa @RFC4320, NTATAG_EXTRA_100(), NTATAG_TIMEOUT_408()
 *
 */
tag_typedef_t ntatag_pass_408 = BOOLTAG_TYPEDEF(pass_408);

/**@def NTATAG_MERGE_482(x)
 *
 * Merge requests, send 482 to other requests. 
 *
 * If an User-Agent receives a duplicate request with same @CallID, @CSeq,
 * @From tag but different topmost @Via header (see @RFC3261 section 8.2.2.2
 * Merged Requests), it should return <i>482 Request Merged</i> response to
 * the duplicate request. Such a duplicate request has been originally
 * generated by a forking proxy and usually routed via different route to
 * the User-Agent. The User-Agent should only respond meaningfully to the
 * first request and return the 482 response to the following forked
 * requests.
 *
 * Note that also NTATAG_UA(1) should be set before nta detects merges and
 * responds with 482 to them.
 *
 * @note If your application is an multi-lined user-agent, you may consider
 * disabling request merging. However, you have to somehow handle merging
 * within a single line.
 *
 * @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 - detect duplicate requests and respond with 482 to them
 *    - false - process duplicate requests separately
 *
 * @sa NTATAG_UA(1)
 */
tag_typedef_t ntatag_merge_482 = BOOLTAG_TYPEDEF(merge_482);

/**@def NTATAG_CANCEL_2543(x)
 *
 *Follow @RFC2543 semantics with CANCEL.
 *
 * By default, the nta follows "@RFC3261" semantics when CANCELing a
 * request. The CANCEL does not terminate transaction, rather, it is just a
 * hint to the server that it should respond immediately (with <i>487
 * Request Terminated</i> if it has no better response). Also, if the
 * original request was sent over unreliable transport such as UDP, the
 * CANCEL is delayed until the server has sent a preliminary response to the
 * original request.
 *
 * If NTATAG_CANCEL_2543(1) is given, the transaction is canceled
 * immediately internally (a 487 response is generated locally) and the
 * CANCEL request is sent without waiting for an provisional response.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *    nta_outgoing_tcancel()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - follow "RFC 2543" semantics with CANCEL
 *    - false - follow "RFC 3261" semantics with CANCEL
 *
 * @sa NTATAG_CANCEL_408()
 */
tag_typedef_t ntatag_cancel_2543 = BOOLTAG_TYPEDEF(cancel_2543);

/**@def NTATAG_CANCEL_408(x)
 *
 * Do not send a CANCEL but just timeout the request. 
 *
 * Calling nta_outgoing_tcancel() with this tag set marks request as
 * canceled but does not actually send a CANCEL request. If
 * NTATAG_CANCEL_2543(1) is also included, a 487 response is generated
 * internally.
 *
 * @par Used with
 *    nta_outgoing_tcancel() \n
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - do not send CANCEL
 *    - false - let request to timeout
 *
 * @sa NTATAG_CANCEL_2543()
 */
tag_typedef_t ntatag_cancel_408 = BOOLTAG_TYPEDEF(cancel_408);

/**@def NTATAG_CANCEL_487(x)
 *
 * When a CANCEL is received, automatically return 487 response to original request.
 *
 * When the CANCEL is received for an ongoing server transaction
 * #nta_incoming_t, the stack will automatically return a <i>487 Request
 * Terminated</i> response to the client after returning from the
 * #nta_incoming_f callback bound to the transaction with
 * nta_incoming_bind()
 * 
 * The application can delay sending the response to the original request
 * when NTATAG_CANCEL_408(0) is used. This is useful, for instance, with a
 * proxy that forwards the CANCEL downstream and the forwards the response
 * back to upstream.
 *
 * @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 - respond automatically to the CANCELed transaction
 *    - false - application takes care of responding
 *
 * @sa NTATAG_CANCEL_2543(), nta_incoming_bind()
 */
tag_typedef_t ntatag_cancel_487 = BOOLTAG_TYPEDEF(cancel_487);

/**@def NTATAG_TAG_3261(x)
 *
 * When responding to requests, use unique tags. 
 *
 * If set the UA would generate an unique @From/@To tag for all dialogs. If
 * unset UA would reuse same tag in order to make it easier to re-establish
 * dialog state after a reboot.
 *
 * @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 - use different tag for each dialog
 *    - false - use same tag for all dialogs
 *
 * @sa @RFC3261 section 12.2.2
 */
tag_typedef_t ntatag_tag_3261 = BOOLTAG_TYPEDEF(tag_3261);

/**@def NTATAG_REL100(x)
 *
 * Include rel100 in INVITE requests. 
 *
 * Include feature tag "100rel" in @Supported header of the INVITE requests.
 *
 * @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 - include "100rel"
 *    - false - do not include "100rel"
 *
 * @sa nta_outgoing_prack(), nta_reliable_treply(), nta_reliable_mreply()
 */
tag_typedef_t ntatag_rel100 = BOOLTAG_TYPEDEF(rel100);

/**@def NTATAG_NO_DIALOG(x)
 *
 * Create a leg without dialog. */
tag_typedef_t ntatag_no_dialog = BOOLTAG_TYPEDEF(no_dialog);

/**@def NTATAG_USE_TIMESTAMP(x)
 *
 * Use @Timestamp header. 
 *
 * If set, a @Timestamp header would be added to stateful requests. The
 * header can be used to calculate the roundtrip transport latency between
 * client and server.
 *
 * @par Used with
 *    nua_create(), 
 *    nta_agent_create(),
 *    nta_agent_set_params(),
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), and nta_outgoing_prack().
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - Add @Timestamp header
 *    - false - do not add @Timestamp header
 *
 * @sa @RFC3261 section 8.2.6
 */
tag_typedef_t ntatag_use_timestamp = BOOLTAG_TYPEDEF(use_timestamp);

/**@def NTATAG_SIPFLAGS(x)
 *
 * Set SIP parser flags. 
 *
 * The SIP parser flags affect how the messages are parsed and the result
 * presented to the application. They also control encoding of messages.
 * The most important flags are as follows:
 * - MSG_FLG_COMPACT - use compact form 
 *                     (single-letter header names, minimum whitespace)
 * - MSG_FLG_EXTRACT_COPY - cache printable copy of headers when parsing. 
 *   Using this flag can speed up proxy processing considerably. It is
 *   implied when the parsed messages are logged (because #TPORT_LOG
 *   environment variable is set, or TPTAG_LOG() is used.
 *
 * @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 SIP parser flags (enum #msg_flg_user)
 *
 * @sa NTATAG_PRELOAD(), enum #msg_flg_user, sip_s::sip_flags
 */
tag_typedef_t ntatag_sipflags = UINTTAG_TYPEDEF(sipflags);

/**@def NTATAG_CLIENT_RPORT(x)
 *
 * Enable client-side "rport". 
 *
 * This tag controls @RFC3581 support on client side. The "rport" parameter
 * is used when the response has to be routed symmetrically through a NAT box.
 *
 * The client-side support involves just adding the "rport" parameter to the topmost
 * @Via header before the request is sent. 
 *
 * @note By default, the client "rport" is disabled when nta is used, and
 * enabled when nua is used.
 *
 * @par Used with
 *    nua_create() (nua uses NTATAG_CLIENT_RPORT(1) by default) \n
 *    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 - add "rport" parameter
 *    - false - do not add "rport" parameter
 *
 * @note The NTATAG_RPORT() is a synonym for this.
 *
 * @sa @RFC3581, NTATAG_SERVER_RPORT(), NTATAG_TCP_RPORT(), @Via
 */
tag_typedef_t ntatag_client_rport = BOOLTAG_TYPEDEF(client_rport);

/**@def NTATAG_SERVER_RPORT(x)
 *
 * Use rport parameter at server.
 *
 * This tag controls @RFC3581 support on server side. The "rport" parameter
 * is used when the response has to be routed symmetrically through a NAT
 * box.
 *
 * If the topmost @Via header has an "rport" parameter, the server stores
 * the port number from which the request was sent in it. When sending the
 * response back to the client, the server uses the port number in the
 * "rport" parameter rather than the client-supplied port number in @Via
 * header.
 *
 * Note that on server-side the port number is stored regardless of the
 * transport protocol. (It is assumed that client supports rport if it
 * includes "rport" parameter in @Via field).
 *
 * @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 - use "rport" parameter (default)
 *    - false - do not use "rport" parameterx
 *
 * @sa @RFC3581, NTATAG_CLIENT_RPORT(), NTATAG_TCP_RPORT(), @Via
 */
tag_typedef_t ntatag_server_rport = UINTTAG_TYPEDEF(server_rport);


/**@def NTATAG_TCP_RPORT(x)
 *
 * Use rport with TCP, too. 
 *
 * @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 - include rport parameter in the TCP via line on client side 
 *    - false - do not include rport parameter in the TCP via line on client side
 *
 * @sa @RFC3581, NTATAG_CLIENT_RPORT(), NTATAG_SERVER_RPORT(), @Via
 */
tag_typedef_t ntatag_tcp_rport = BOOLTAG_TYPEDEF(tcp_rport);

/**@def NTATAG_PRELOAD(x)
 *
 * Preload by N bytes. 
 *
 * When the memory block is allocated for an incoming request by the stack,
 * the stack can allocate some extra memory for the parser in addition to
 * the memory used by the actual message contents. 
 * 
 * While wasting some memory, this can speed up parsing considerably.
 * Recommended amount of preloading per packet is 1500 bytes.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *    unsigned
 *
 * @par Values
 *    Amount of extra per-message memory allocated for parser.
 *
 * @sa NTATAG_SIPFLAGS() and #MSG_FLG_EXTRACT_COPY
 */
tag_typedef_t ntatag_preload = UINTTAG_TYPEDEF(preload);

/**@def NTATAG_USE_NAPTR(x)
 *
 * If true, try to use NAPTR records when resolving. 
 *
 * The application can disable NTA from using NAPTR records when resolving
 * SIP URIs.
 *
 * @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 - enable NAPTR resolving
 *    - false - disable NAPTR resolving
 *
 * @bug NAPTRs are not used with SIPS URIs in any case.
 *
 * @sa @RFC3263, NTATAG_USE_SRV()
 */