nua_tag.c

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

 * request if NUTAG_UPDATE_REFRESH(1) parameter tag has been set).
 * 
 * @par When to Use NUTAG_SESSION_TIMER()?
 *
 * The session time extension is enabled ("timer" feature tag is included in
 * @Supported header) but not activated by default (no @SessionExpires
 * header is included in the requests or responses by default). Using
 * non-zero value with NUTAG_SESSION_TIMER() or NUTAG_SESSION_REFRESHER()
 * activates it. When the extension is activated, @nua refreshes the call
 * state by sending periodic re-INVITE or UPDATE requests unless the remote
 * end indicated that it will take care of refreshes.
 *
 * The session timer extension is mainly useful for proxies or back-to-back
 * user agents that keep call state. The call state is "soft" meaning that
 * if no call-related SIP messages are processed for certain time the state
 * will be destroyed. An ordinary user-agent can also make use of session
 * timer if it cannot get any activity feedback from RTP or other media.
 *
 * @note The session timer extension is used only if the feature
 * tag "timer" is listed in the @Supported header, set by NUTAG_SUPPORTED(),
 * SIPTAG_SUPPORTED(), or SIPTAG_SUPPORTED_STR() tags.
 *
 * @par Used with
 *    nua_invite(), nua_update(), nua_respond() \n
 *    nua_set_params() or nua_set_hparams() \n
 *    nua_get_params() or nua_get_hparams()
 *
 * See nua_set_hparams() for a complete list of the the nua operations that
 * accept this tag.
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    @c 0  disable \n
 *    @c >0 interval in seconds
 *
 * Corresponding tag taking reference parameter is NUTAG_SESSION_TIMER_REF().
 *
 * @sa NUTAG_SUPPORTED(), NUTAG_MIN_SE(), NUTAG_SESSION_REFRESHER(),
 * nua_invite(), #nua_r_invite, #nua_i_invite, nua_respond(), 
 * nua_update(), #nua_r_update, #nua_i_update, 
 * NUTAG_UPDATE_REFRESH(), @RFC4028, @SessionExpires, @MinSE
 */
tag_typedef_t nutag_session_timer = UINTTAG_TYPEDEF(session_timer);

/**@def NUTAG_SESSION_TIMER_REF(x) 
 * Reference tag for NUTAG_SESSION_TIMER().
 */


/**@def NUTAG_MIN_SE(x)
 *
 * Minimum acceptable refresh interval for session.
 *
 * Specifies the value of @MinSE header in seconds. The @b Min-SE header is
 * used to specify minimum acceptable refresh interval for session timer
 * extension.
 *
 * @par Used with
 *    nua_handle(), nua_invite(), nua_update(), nua_respond() \n
 *    nua_set_params() or nua_set_hparams() \n
 *    nua_get_params() or nua_get_hparams()
 *
 * See nua_set_hparams() for a complete list of the nua operations that
 * accept this tag.
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    interval in seconds.
 *
 * Corresponding tag taking reference parameter is NUTAG_MIN_SE_REF().
 *
 * @sa NUTAG_SESSION_TIMER(), NUTAG_SESSION_REFRESHER(),
 * NUTAG_UPDATE_REFRESH(), @RFC4028, @MinSE, @SessionExpires
 */
tag_typedef_t nutag_min_se = UINTTAG_TYPEDEF(min_se);

/**@def NUTAG_MIN_SE_REF(x) 
 * Reference tag for NUTAG_MIN_SE().
 */


/**@def NUTAG_SESSION_REFRESHER(x)
 *
 * Specify the preferred refresher.
 *
 * Specify for session timer extension which party is the preferred refresher.
 *
 * @par Used with
 *    nua_handle(), nua_invite(), nua_update(), nua_respond() \n
 *    nua_set_params() or nua_set_hparams() \n
 *    nua_get_params() or nua_get_hparams()
 *
 * See nua_set_hparams() for a complete list of all the nua operations that
 * accept this tag.
 *
 * @par Parameter type
 *   enum { #nua_no_refresher,  #nua_local_refresher, #nua_remote_refresher,
 *          #nua_any_refresher }
 *
 * @par Values
 *    @c nua_no_refresher (session timers are disabled) \n
 *    @c nua_local_refresher \n
 *    @c nua_remote_refresher \n
 *    @c nua_any_refresher (default) \n
 *
 * Corresponding tag taking reference parameter is
 * NUTAG_SESSION_REFRESHER_REF().
 *
 * @sa NUTAG_SESSION_TIMER(), NUTAG_MIN_SE_REF(),
 * NUTAG_UPDATE_REFRESH(), @RFC4028, @SessionExpires, @MinSE
 */
tag_typedef_t nutag_session_refresher = INTTAG_TYPEDEF(session_refresher);

/**@def NUTAG_SESSION_REFRESHER_REF(x) 
 * Reference tag for NUTAG_SESSION_REFRESHER().
 */




/**@def NUTAG_UPDATE_REFRESH(x)
 *
 * Use UPDATE as refresh method.
 *
 * If this parameter is true and the remote endpoint has included UPDATE in
 * Allow header, the nua stack uses UPDATE instead of INVITE to refresh the 
 * session when using the session timer extension.
 *
 * Note that the session timer headers @SessionExpires and @MinSE are always
 * included in the UPDATE request and responses regardless of the value of
 * this tag.
 *
 * @par Used with
 *    nua_handle(), nua_invite(), nua_update(), nua_respond() \n
 *    nua_set_params() or nua_set_hparams() \n
 *    nua_get_params() or nua_get_hparams()
 *
 * See nua_set_hparams() for a complete list of all the nua operations that
 * accept this tag.
 *
 * @par Parameter type
 *    boolean
 *
 * @par Values
 *    @c 1 Use UPDATE \n
 *    @c 0 Use INVITE
 *
 * Corresponding tag taking reference parameter is NUTAG_UPDATE_REFRESH_REF().
 *
 * @sa #nua_r_update, NUTAG_SESSION_TIMER(), NUTAG_MIN_SE_REF(),
 * NUTAG_UPDATE_REFRESH(), @RFC4028, @SessionExpires, @MinSE
 */
tag_typedef_t nutag_update_refresh = BOOLTAG_TYPEDEF(update_refresh);

/**@def NUTAG_UPDATE_REFRESH_REF(x) 
 * Reference tag for NUTAG_UPDATE_REFRESH().
 */


/**@def NUTAG_REFER_EXPIRES()
 *
 * Default lifetime for implicit subscriptions created by REFER.
 *
 * Default expiration time in seconds for implicit subscriptions created by
 * REFER.
 *
 * @par Used with
 *    nua_handle(), nua_respond() \n
 *    nua_set_params() or nua_set_hparams() \n
 *    nua_get_params() or nua_get_hparams()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - default interval in seconds
 *
 * @sa NUTAG_SUB_EXPIRES()
 *
 * Corresponding tag taking reference parameter is NUTAG_REFER_EXPIRES_REF().
 */
tag_typedef_t nutag_refer_expires = UINTTAG_TYPEDEF(refer_expires);

/**@def NUTAG_REFER_EXPIRES_REF(x) 
 * Reference tag for NUTAG_REFER_EXPIRES().
 */


/**@def NUTAG_REFER_WITH_ID()
 *
 * Always use id parameter with refer event.
 *
 * When an incoming REFER creates an implicit subscription, the event header
 * in the NOTIFY request may have an id parameter. The id parameter can be
 * either always included (default behavior), or the parameter can be used
 * only for the second and subsequent REFER requests received in a given
 * dialog.
 *
 * Note that once the subscription is created, the event header should not
 * be modified. Therefore this tag has no effect on already established
 * subscriptions, and its use makes sense largely on nua_set_params() only.
 *
 * @par Used with
 *    nua_set_params() (nua_set_hparams(), nua_invite(), nua_respond(),
 *    nua_update()).
 *
 * @par Parameter type
 *    int (boolean)
 *
 * @par Values
 *   0 (false, do not use id with subscription created with first REFER request) \n
 *   1 (true, use id with all subscriptions created with REFER request) \n
 *
 * Corresponding tag taking reference parameter is NUTAG_REFER_WITH_ID_REF().
 *
 * @since New in @VERSION_1_12_2.
 */
tag_typedef_t nutag_refer_with_id = BOOLTAG_TYPEDEF(refer_with_id);

/**@def NUTAG_REFER_WITH_ID_REF(x) 
 * Reference tag for NUTAG_REFER_WITH_ID().
 */

/**@def NUTAG_AUTOALERT(x)
 *
 * Send alerting (180 Ringing) automatically
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   No automatic sending of "180 Ringing" \n
 *    @c !=0 "180 Ringing" sent automatically
 *
 * Corresponding tag taking reference parameter is NUTAG_AUTOALERT_REF().
 */
tag_typedef_t nutag_autoalert = BOOLTAG_TYPEDEF(autoAlert);

/**@def NUTAG_AUTOALERT_REF(x) 
 * Reference tag for NUTAG_AUTOALERT().
 */


/**@def NUTAG_AUTOANSWER(x)
 *
 * Answer (with 200 Ok) automatically to incoming call.
 *
 * @par Used with
 *    nua_set_params(), nua_set_hparams() \n
 *    nua_get_params(), nua_get_hparams() \n
 *    nua_invite() \n
 *    nua_respond()
 *
 * @par Parameter type
 *    int (boolean)
 *
 * @par Values
 *    @c 0    No automatic sending of "200 Ok" \n
 *    @c !=0 "200 Ok" sent automatically
 *
 * Corresponding tag taking reference parameter is NUTAG_AUTOANSWER_REF().
 *
 * @note Requires that @soa is enabled with NUTAG_MEDIA_ENABLE(1).
 * 
 * @par Auto-Answer to Re-INVITE requests
 * By default, NUA tries to auto answer the re-INVITEs used to refresh the
 * session when the media is enabled. Set NUTAG_AUTOANSWER(0) on the call
 * handle (e.g., include the tag with nua_invite(), nua_respond()) in order
 * to disable the auto answer on re-INVITEs.
 *
 * @bug If the re-INVITE modifies the session (e.g., SDP contains offer that
 * adds video stream to the session), NUA auto-answers it if
 * NUTAG_AUTOANSWER(0) has not been set on the handle. It accepts or rejects
 * media based on the existing user SDP (set with SOATAG_USER_SDP(), for
 * example). It should auto-answer only session refresh request and let
 * application decide how to handle requests to modify the session.
 *
 * @sa NUTAG_MEDIA_ENABLE(), NUTAG_AUTOALERT(), NUTAG_AUTOACK().
 */
tag_typedef_t nutag_autoanswer = BOOLTAG_TYPEDEF(autoAnswer);

/**@def NUTAG_AUTOANSWER_REF(x) 
 * Reference tag for NUTAG_AUTOANSWER().
 */


/**@def NUTAG_AUTOACK(x)
 *
 * ACK automatically
 *
 * If this parameter is true, ACK is sent automatically after receiving 2XX
 * series response to INVITE. Note that ACK is always sent automatically by
 * lower layers of the stack after receiving an error response 3XX, 4XX, 5XX
 * or 6XX.
 *
 * @par Used with
 *    nua_set_params(), nua_set_hparams(), \n
 *    nua_get_params(), nua_get_hparams(), \n
 *    nua_invite(), nua_ack(), nua_respond(), nua_update() \n
 *    nua_respond()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0    No automatic sending of ACK \n
 *    @c !=0 ACK sent automatically
 *
 * Default value is NUTAG_AUTOACK(1).
 * 
 * Corresponding tag taking reference parameter is NUTAG_AUTOACK_REF().
 */
tag_typedef_t nutag_autoack = BOOLTAG_TYPEDEF(autoACK);

/**@def NUTAG_AUTOACK_REF(x) 
 * Reference tag for NUTAG_AUTOACK().
 */


/**@def NUTAG_ENABLEINVITE(x)
 *
 * Enable incoming INVITE.
 *
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   Incoming INVITE not enabled. NUA answers 403 Forbidden \n
 *    @c !=0 Incoming INVITE enabled
 *
 * Corresponding tag taking reference parameter is NUTAG_ENABLEINVITE_REF().
 */
tag_typedef_t nutag_enableinvite = BOOLTAG_TYPEDEF(enableInvite);

/**@def NUTAG_ENABLEINVITE_REF(x) 
 * Reference tag for NUTAG_ENABLEINVITE().
 */



/**@def NUTAG_ENABLEMESSAGE(x)
 *
 * Enable incoming MESSAGE
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   Incoming MESSAGE not enabled. NUA answers 403 Forbidden \n
 *    @c !=0 Incoming MESSAGE enabled
 *
 * Corresponding tag taking reference parameter is NUTAG_ENABLEMESSAGE_REF().
 */
tag_typedef_t nutag_enablemessage = BOOLTAG_TYPEDEF(enableMessage);

/**@def NUTAG_ENABLEMESSAGE_REF(x) 
 * Reference tag for NUTAG_ENABLEMESSAGE().
 */



/**@def NUTAG_ENABLEMESSENGER(x)
 *
 * Enable incoming MESSAGE with To tag.
 *
 * Set this parameter if you want to chat with Windows Messenger.
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   False \n
 *    @c !=0 True
 *
 * Corresponding tag taking reference parameter is NUTAG_ENABLEMESSENGER_REF().
 */
tag_typedef_t nutag_enablemessenger = BOOLTAG_TYPEDEF(enableMessenger);

/**@def NUTAG_ENABLEMESSENGER_REF(x) 
 * Reference tag for NUTAG_ENABLEMESSENGER().
 */


/**@def NUTAG_SMIME_ENABLE(x)
 *
 * Enable S/MIME
 *
 * @par Used with
 *    nua_create() \n
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *    boolean
 *
 * @par Values
 *    @c 0   S/MIME is Disabled \n
 *    @c !=0 S/MIME is Enabled
 *
 * Corresponding tag taking reference parameter is NUTAG_SMIME_ENABLE_REF().
 */
tag_typedef_t nutag_smime_enable = BOOLTAG_TYPEDEF(smime_enable);

/**@def NUTAG_SMIME_ENABLE_REF(x) 
 * Reference tag for NUTAG_SMIME_ENABLE().
 */


/**@def NUTAG_SMIME_OPT(x)
 *
 * S/MIME Options
 *
 * This tag specifies the type of S/MIME security services requested
 * by the user.
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params() \n
 *    nua_message()
 *
 * @par Parameter type
 *   int
 *
 * @par Values
 *   @c -1 (SM_ID_NULL) No security service needed \n
 *   @c  0 (SM_ID_CLEAR_SIGN) Clear signing \n
 *   @c  1 (SM_ID_SIGN) S/MIME signing \n
 *   @c  2 (SM_ID_ENCRYPT) S/MIME encryption
 *
 * Corresponding tag taking reference parameter is NUTAG_SMIME_OPT_REF().
 */
tag_typedef_t nutag_smime_opt = INTTAG_TYPEDEF(smime_opt);

/**@def NUTAG_SMIME_OPT_REF(x) 
 * Reference tag for NUTAG_SMIME_OPT().
 */


/**@def NUTAG_SMIME_PROTECTION_MODE(x)
 *
 * S/MIME protection mode
 *
 * This tag specifies the protection mode of the SIP message by
 * S/MIME as requested by the user
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *   unsigned int
 *
 * @par Values