nua_tag.c

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

/**@def NUTAG_EARLY_ANSWER(x)
 *
 * Establish early media session by including SDP answer in 1XX response.
 *
 * @par Used with
 *    nua_respond(), nua_set_params(), nua_set_hparams()
 *
 * @par Parameter type
 *    int (boolean)
 *
 * @par Values
 *    @c 0   False \n
 *    @c !=0 True
 *
 * Corresponding tag taking reference parameter is NUTAG_EARLY_ANSWER_REF().
 *
 * @note Requires that @soa is enabled with NUTAG_MEDIA_ENABLE(1).
 *
 * @sa NUTAG_EARLY_MEDIA(), NUTAG_AUTOALERT(), NUTAG_MEDIA_ENABLE()
 * 
 * @since New in @VERSION_1_12_2.
 */
tag_typedef_t nutag_early_answer = BOOLTAG_TYPEDEF(early_answer);

/**@def NUTAG_EARLY_ANSWER_REF(x) 
 * Reference tag for NUTAG_EARLY_ANSWER().
 */


/**@def NUTAG_INCLUDE_EXTRA_SDP(x)
 *
 * Include an extra copy of SDP answer in the response.
 *
 * When NUTAG_INCLUDE_EXTRA_SDP(1) is included in nua_respond() tags, stack
 * will include in the response a copy of the SDP offer/answer that was last
 * sent to the client. This tag should be used only when you know that the
 * remote end requires the extra SDP, for example, some versions of Cisco
 * SIPGateway need a copy of answer in 200 OK even when they indicate
 * support for 100rel.
 *
 * @par Used with
 *    nua_respond()
 *
 * @par Parameter type
 *    int (boolean)
 *
 * @par Values
 *    @c 0   False \n
 *    @c !=0 True
 *
 * Corresponding tag taking reference parameter is
 * NUTAG_INCLUDE_EXTRA_SDP_REF().
 *
 * @note Requires that @soa is enabled with NUTAG_MEDIA_ENABLE(1).
 *
 * @sa NUTAG_EARLY_ANSWER(), NUTAG_EARLY_MEDIA(), NUTAG_AUTOALERT(),
 * NUTAG_MEDIA_ENABLE(), @RFC3264, @RFC3264
 * 
 * @since New in @VERSION_1_12_4.
 */
tag_typedef_t nutag_include_extra_sdp = BOOLTAG_TYPEDEF(include_extra_sdp);

/**@def NUTAG_INCLUDE_EXTRA_SDP_REF(x) 
 * Reference tag for NUTAG_INCLUDE_EXTRA_SDP().
 */


/**@def NUTAG_MEDIA_ENABLE()
 *
 * Enable built-in media session handling
 *
 * The built-in media session object @soa takes care of most details
 * of offer-answer negotiation. 
 *
 * @par Used with
 *    nua_create()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   False \n
 *    @c !=0 True
 *
 * Corresponding tag taking reference parameter is NUTAG_MEDIA_ENABLE_REF()
 */
tag_typedef_t nutag_media_enable = BOOLTAG_TYPEDEF(media_enable);

/**@def NUTAG_MEDIA_ENABLE_REF(x) 
 * Reference tag for NUTAG_MEDIA_ENABLE().
 */



/**@def NUTAG_SOA_NAME(x)
 *
 * Name for SDP Offer-Answer session object.
 *
 * SDP Offer-Answer session object name.
 *
 * @par Used with nua_create(), nua_handle().
 *
 * @par Parameter type
 *    void * (actually soa_session_t *)
 *
 * @par Values
 *    Pointer to MSS media session.
 *
 * Corresponding tag taking reference parameter is NUTAG_SOA_NAME_REF().
 */
tag_typedef_t nutag_soa_name = STRTAG_TYPEDEF(soa_name);

/**@def NUTAG_SOA_NAME_REF(x) 
 * Reference tag for NUTAG_SOA_NAME().
 */


/**@def NUTAG_RETRY_COUNT(x)
 * 
 * Set request retry count.
 *
 * Retry count determines how many times stack will automatically retry
 * after an recoverable error response, like 302, 401 or 407.
 *
 * Note that the first request does not count as retry.
 *
 * @par Used with
 *    nua_create(), nua_set_params(), nua_handle(), nua_set_hparams(),
 *    nua_get_params(), nua_get_hparams(),
 *    nua_register(), nua_unregister(),
 *    nua_options(), nua_invite(), nua_ack(), nua_cancel(), nua_bye(),
 *    nua_prack(), nua_update(), nua_info(),
 *    nua_message(), nua_publish(), nua_unpublish(), nua_notifier(),
 *    nua_subscribe(), nua_unsubscribe(), nua_notify(), nua_refer(), 
 *    nua_method(), nua_respond()
 *    nua_authenticate().
 *
 * @par Parameter type
 *    unsigned
 *
 * @par Values
 * - 0 - Never retry automatically \n
 * - Otherwise, number of extra transactions initiated after initial
 *   transaction failed with recoverable error response
 *
 * @NEW_1_12_4.
 *
 * Corresponding tag taking reference parameter is NUTAG_RETRY_COUNT_REF().
 */
tag_typedef_t nutag_retry_count = UINTTAG_TYPEDEF(retry_count);

/**@def NUTAG_RETRY_COUNT_REF(x) 
 *
 * Reference tag for NUTAG_RETRY_COUNT().
 */


/**@def NUTAG_MAX_SUBSCRIPTIONS(x)
 *
 * Set maximum number of simultaneous subscribers per single event server.
 *
 * Determines how many subscribers can simultaneously subscribe to a single
 * event.
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *    unsigned
 *
 * @par Values
 *    @c 0   Do not allow any subscriptions \n
 *
 * @sa nua_notifier(), nua_authorize()
 *
 * Corresponding tag taking reference parameter is 
 * NUTAG_MAX_SUBSCRIPTIONS_REF().
 */
tag_typedef_t nutag_max_subscriptions = UINTTAG_TYPEDEF(max_subscriptions);

/**@def NUTAG_MAX_SUBSCRIPTIONS_REF(x) 
 * Reference tag for NUTAG_MAX_SUBSCRIPTIONS().
 */


/**@def NUTAG_CALLSTATE()
 *
 * Call state
 *
 * @par Used with
 *    #nua_i_state
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 * - #nua_callstate_init - Initial state
 * - #nua_callstate_authenticating - 401/407 received
 * - #nua_callstate_calling - INVITE sent
 * - #nua_callstate_proceeding - 18X received
 * - #nua_callstate_completing   - 2XX received
 * - #nua_callstate_received - INVITE received (and 100 Trying sent)
 * - #nua_callstate_early       - 18X sent
 * - #nua_callstate_completed   - 2XX sent
 * - #nua_callstate_ready       - 2XX and ACK received/sent
 * - #nua_callstate_terminating - BYE sent
 * - #nua_callstate_terminated  - BYE complete
 *
 * Corresponding tag taking reference parameter is NUTAG_CALLSTATE_REF().
 */
tag_typedef_t nutag_callstate = INTTAG_TYPEDEF(callstate);

/**@def NUTAG_CALLSTATE_REF(x) 
 * Reference tag for NUTAG_CALLSTATE().
 */


/**@def NUTAG_OFFER_RECV()
 *
 * Indicate that SDP offer has been received.
 *
 * @par Used with
 *    #nua_i_state
 *
 * @par Parameter type
 *    boolean
 *
 * Corresponding tag taking reference parameter is NUTAG_OFFER_RECV_REF().
 */
tag_typedef_t nutag_offer_recv = BOOLTAG_TYPEDEF(offer_recv);

/**@def NUTAG_OFFER_RECV_REF(x) 
 * Reference tag for NUTAG_OFFER_RECV().
 */


/**@def NUTAG_ANSWER_RECV()
 *
 * Indicate that SDP answer has been received.
 *
 * @par Used with
 *    #nua_i_state
 *
 * @par Parameter type
 *    boolean
 *
 * Corresponding tag taking reference parameter is NUTAG_ANSWER_RECV_REF().
 */
tag_typedef_t nutag_answer_recv = BOOLTAG_TYPEDEF(answer_recv);

/**@def NUTAG_ANSWER_RECV_REF(x) 
 * Reference tag for NUTAG_ANSWER_RECV().
 */


/**@def NUTAG_OFFER_SENT()
 *
 * Indicate that SDP offer has been sent.
 *
 * @par Used with
 *    #nua_i_state
 *
 * @par Parameter type
 *    boolean
 *
 * Corresponding tag taking reference parameter is NUTAG_OFFER_SENT_REF().
 */
tag_typedef_t nutag_offer_sent = BOOLTAG_TYPEDEF(offer_sent);

/**@def NUTAG_OFFER_SENT_REF(x) 
 * Reference tag for NUTAG_OFFER_SENT().
 */


/**@def NUTAG_ANSWER_SENT()
 *
 * Indicate that SDP answer has been sent.
 *
 * @par Used with
 *    #nua_i_state
 *
 * @par Parameter type
 *    int (boolean: nonzero is true, zero is false)
 *
 * Corresponding tag taking reference parameter is NUTAG_ANSWER_SENT_REF().
 */
tag_typedef_t nutag_answer_sent = BOOLTAG_TYPEDEF(answer_sent);

/**@def NUTAG_ANSWER_SENT_REF(x) 
 * Reference tag for NUTAG_ANSWER_SENT().
 */


/**@def NUTAG_SUBSTATE()
 *
 * Subscription state.
 *
 * @par Used with
 * - with nua_create(), nua_set_params(), nua_get_params(),
 *   nua_handle(), nua_set_hparams(), nua_get_hparams(), and
 *   nua_notifier() to change the default subscription state returned by
 *   the internal event server
 * - with nua_notify() and nua_respond() to SUBSCRIBE to determine the
 *   subscription state (if application include @SubscriptionState
 *   header in the tag list, the NUTAG_SUBSTATE() value is ignored)
 * - with #nua_r_subscribe, #nua_i_notify, #nua_i_subscribe, and #nua_r_notify
 *   to indicate the current subscription state
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *   - #nua_substate_embryonic (0)
 *   - #nua_substate_pending (1)
 *   - #nua_substate_active (2)
 *   - #nua_substate_terminated (3)
 *
 * Note that the @SubscriptionState or @Expires headers specified by
 * application with the nua_notify() or nua_respond() to SUBSCRIBE overrides
 * the subscription state specified by NUTAG_SUBSTATE(). 
 * Application can terminate subscription by including
 * NUTAG_SUBSTATE(nua_substate_terminated), @SubscriptionState with value
 * "terminated" or @Expires header with value 0 in the NOTIFY request sent
 * by nua_notify().
 *
 * @sa @RFC3265, @SubscriptionState, SIPTAG_SUBSCRIPTION_STATE(),
 * SIPTAG_SUBSCRIPTION_STATE_STR(), nua_notifier(), #nua_r_subscribe,
 * #nua_i_subscribe, #nua_i_refer, #nua_r_notify, #nua_i_notify.
 *
 * Corresponding tag taking reference parameter is NUTAG_SUBSTATE_REF().
 */
tag_typedef_t nutag_substate = INTTAG_TYPEDEF(substate);

/**@def NUTAG_SUBSTATE_REF(x) 
 * Reference tag for NUTAG_SUBSTATE().
 */


/**@def NUTAG_SUB_EXPIRES()
 *
 * Default expiration time of subscriptions.
 *
 * @par Used with
 * - with nua_create(), nua_set_params(), nua_get_params(), nua_handle(),
 *   nua_set_hparams(), nua_get_hparams(), nua_respond(), nua_notify(), and
 *   nua_notifier() to change the default expiration time of subscriptions
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *   - default expiration time in seconds
 *
 * Note that the expires parameter in @SubscriptionState or @Expires header
 * in the nua_response() to the SUBSCRIBE overrides the default subscription
 * expiration specified by NUTAG_SUB_EXPIRES().
 *
 * @sa @RFC3265, NUTAG_REFER_EXPIRES(), @Expires, SIPTAG_EXPIRES(),
 * SIPTAG_EXPIRES_STR(), @SubscriptionState, nua_respond(), nua_notifier(),
 * #nua_r_subscribe, #nua_i_subscribe, #nua_r_refer, #nua_r_notify,
 * #nua_i_notify.
 *
 * Corresponding tag taking reference parameter is NUTAG_SUB_EXPIRES_REF().
 *
 * @NEW_1_12_9.
 */
tag_typedef_t nutag_sub_expires = UINTTAG_TYPEDEF(substate);

/**@def NUTAG_SUB_EXPIRES_REF(x) 
 * Reference tag for NUTAG_SUB_EXPIRES().
 */


/**@def NUTAG_NEWSUB()
 *
 * Send unsolicited NOTIFY request.
 *
 * Some applications may require sending unsolicited NOTIFY requests, that
 * is, NOTIFY without SUBSCRIBE or REFER request sent by event watcher. 
 * However, sending NOTIFY request requires an existing dialog usage by
 * default. If the nua_notify() tags include NUTAG_NEWSUB(1), the usage
 * is created by nua_notify() itself.
 *
 * If you want to create a subscription that does not terminate immediately
 * include SIPTAG_SUBSCRIPTION_STATE()/SIPTAG_SUBSCRIPTION_STATE_STR() with
 * an "expires" parameter in the argument list, too.
 *
 * @par Used with
 *    nua_notify()
 *
 * @par Parameter type
 *    int (boolean)
 *
 * @par Values
 *   - 0 - false (default) - do not create new subscription 
 *         but reject NOTIFY with 481 locally \n
 *   - 1 - true - create a subscription if it does not exist \n
 *
 * Corresponding tag taking reference parameter is NUTAG_NEWSUB_REF().
 *
 * @NEW_1_12_5.
 */
tag_typedef_t nutag_newsub = BOOLTAG_TYPEDEF(newsub);

/**@def NUTAG_NEWSUB_REF(x) 
 * Reference tag for NUTAG_NEWSUB().
 */


/**@def NUTAG_INVITE_TIMER(x)
 *
 * Timer for outstanding INVITE in seconds.
 *
 * INVITE will be canceled if no answer is received before timer expires.
 *
 * @par Used with
 *    nua_invite() \n
 *    nua_set_params(), nua_set_hparams(),
 *    nua_get_params(), nua_get_hparams()
 *
 * @par Parameter type
 *    int (enum nua_af)
 *
 * @par Values
 *    @c 0  no timer \n
 *    @c >0 timer in seconds
 *
 * Corresponding tag taking reference parameter is NUTAG_INVITE_TIMER_REF().
 */
tag_typedef_t nutag_invite_timer = UINTTAG_TYPEDEF(invite_timer);

/**@def NUTAG_INVITE_TIMER_REF(x) 
 * Reference tag for NUTAG_INVITE_TIMER().
 */


/**@def NUTAG_SESSION_TIMER(x)
 *
 * Default session timer in seconds.
 *
 * Set default value for session timer in seconds when the session timer
 * extension is used. The tag value is the proposed session expiration time
 * in seconds, the session is refreshed twice during the expiration time.
 *
 * @par Sending INVITE and UPDATE Requests 
 *
 * If NUTAG_SESSION_TIMER() is used with non-zero value, the value is used
 * in the @SessionExpires header included in the INVITE or UPDATE requests. 
 * The intermediate proxies or the ultimate destination can lower the
 * interval in @SessionExpires header. If the value is too low, they can
 * reject the request with the status code <i>422 Session Timer Too
 * Small</i>. In that case, @b nua increases the value of @SessionExpires
 * header and retries the request automatically.
 *
 * @par Returning a Response to the INVITE and UPDATE Requests 
 *
 * The NUTAG_SESSION_TIMER() value is also used when sending the final
 * response to the INVITE or UPDATE requests. If the NUTAG_SESSION_TIMER()
 * value is 0 or the value in the @SessionExpires header of the request is
 * lower than the value in NUTAG_SESSION_TIMER(), the value from the
 * incoming @SessionExpires header is used. However, if the value in
 * @SessionExpires is lower than the minimal acceptable session expiration
 * interval specified with the tag NUTAG_MIN_SE() the request is
 * automatically rejected with <i>422 Session Timer Too Small</i>.
 *
 * @par Refreshes
 *
 * After the initial INVITE request, the SIP session is refreshed at the
 * intervals indicated by the @SessionExpires header returned in the 2XX
 * response. The party indicated with the "refresher" parameter of the
 * @SessionExpires header sends a re-INVITE requests (or an UPDATE