nua_tag.c

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

tag_typedef_t nutag_instance = STRTAG_TYPEDEF(instance);

/**@def NUTAG_INSTANCE_REF(x) 
 * Reference tag for NUTAG_INSTANCE().
 */


/**@def NUTAG_OUTBOUND(x)
 *
 * Outbound option string.
 *
 * The outbound option string can specify how the NAT traversal is handled.
 * The option tokens are as follows:
 * - "gruuize": try to generate a GRUU contact from REGISTER response
 * - "outbound": use SIP outbound extension (off by default)
 * - "validate": validate registration behind a NAT by sending OPTIONS to self
 * - "natify": try to traverse NAT
 * - "use-rport": use rport to traverse NAT
 * - "options-keepalive": send periodic OPTIONS requests as keepalive messages
 *
 * An option token with "no-" or "not-" prefix turns the option off. For
 * example, if you want to try to traverse NATs but not to use OPTIONS
 * keepalive, use NUTAG_OUTBOUND("natify no-options-keepalive").
 * 
 * An empty string can be passed to let the stack choose the
 * default values for outbound usage (in the 1.12.5 release, the
 * defaults are: "gruuize no-outbound validate use-port options-keepalive").
 *
 * @note
 * Options string is used so that no new tags need to be added when the
 * outbound functionality changes.
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *    nua_set_hparams() \n
 *    nua_get_hparams()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_OUTBOUND_REF().
 */
tag_typedef_t nutag_outbound = STRTAG_TYPEDEF(outbound);

/**@def NUTAG_OUTBOUND_REF(x) 
 * Reference tag for NUTAG_OUTBOUND().
 */


/*#@def NUTAG_OUTBOUND_SET1(x)
 *
 * Outbound proxy set 1.
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *    nua_set_hparams() \n
 *    nua_get_hparams()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_OUTBOUND_SET1_REF().
 */
tag_typedef_t nutag_outbound_set1 = STRTAG_TYPEDEF(outbound_set1);

/*#@def NUTAG_OUTBOUND_SET1_REF(x) 
 * Reference tag for NUTAG_OUTBOUND_SET1().
 */


/*#@def NUTAG_OUTBOUND_SET2(x)
 *
 * Outbound proxy set 2.
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *    nua_set_hparams() \n
 *    nua_get_hparams()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_OUTBOUND_SET2_REF().
 */
tag_typedef_t nutag_outbound_set2 = STRTAG_TYPEDEF(outbound_set2);

/*#@def NUTAG_OUTBOUND_SET2_REF(x) 
 * Reference tag for NUTAG_OUTBOUND_SET2().
 */


/*#@def NUTAG_OUTBOUND_SET3(x)
 *
 * Outbound proxy set 3.
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *    nua_set_hparams() \n
 *    nua_get_hparams()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_OUTBOUND_SET3_REF().
 */
tag_typedef_t nutag_outbound_set3 = STRTAG_TYPEDEF(outbound_set3);

/*#@def NUTAG_OUTBOUND_SET3_REF(x) 
 * Reference tag for NUTAG_OUTBOUND_SET3().
 */


/*#@def NUTAG_OUTBOUND_SET4(x)
 *
 * Outbound proxy set 4.
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *    nua_set_hparams() \n
 *    nua_get_hparams()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_OUTBOUND_SET4_REF().
 */
tag_typedef_t nutag_outbound_set4 = STRTAG_TYPEDEF(outbound_set4);

/*#@def NUTAG_OUTBOUND_SET4_REF(x) 
 * Reference tag for NUTAG_OUTBOUND_SET4().
 */



/**@def NUTAG_KEEPALIVE(x)
 *
 * Keepalive interval in milliseconds.
 *
 * This setting applies to OPTIONS/STUN keepalives. See documentation 
 * for nua_register() for more detailed information.
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *    nua_set_hparams() \n
 *    nua_get_hparams()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values 
 *   - 0 - disable keepalives
 *   - 120000 - default value (120000 milliseconds, 120 seconds)
 *
 * Corresponding tag taking reference parameter is
 * NUTAG_KEEPALIVE_REF().
 */
tag_typedef_t nutag_keepalive = UINTTAG_TYPEDEF(keepalive);

/**@def NUTAG_KEEPALIVE_REF(x) 
 * Reference tag for NUTAG_KEEPALIVE().
 */


/**@def NUTAG_KEEPALIVE_STREAM(x)
 *
 * Transport-level keepalive interval for streams.
 *
 * See documentation for nua_register() for more detailed information.
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *    nua_set_hparams() \n
 *    nua_get_hparams()
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values 
 *
 * Transport-level keepalive interval for streams in milliseconds. If this
 * parameter specified, it takes presedence over value given in
 * NUTAG_KEEPALIVE().
 *
 * Corresponding tag taking reference parameter is
 * NUTAG_KEEPALIVE_STREAM_REF().
 *
 * @todo Actually pass NUTAG_KEEPALIVE_STREAM() to transport layer.
 */
tag_typedef_t nutag_keepalive_stream = UINTTAG_TYPEDEF(keepalive_stream);

/**@def NUTAG_KEEPALIVE_STREAM_REF(x) 
 * Reference tag for NUTAG_KEEPALIVE_STREAM().
 */



/**@def NUTAG_USE_DIALOG(x)
 *
 * Ask NUA to create dialog for this handle
 *
 * @par Used with nua calls that send a SIP request
 *
 * @par Parameter type
 *   int
 *
 * @par Values
 *    @c False (zero) \n
 *    @c True (nonzero)
 *
 * Corresponding tag taking reference parameter is NUTAG_USE_DIALOG_REF().
 */
tag_typedef_t nutag_use_dialog = BOOLTAG_TYPEDEF(use_dialog);

/**@def NUTAG_USE_DIALOG_REF(x) 
 * Reference tag for NUTAG_USE_DIALOG().
 */


/**@def NUTAG_AUTH(x)
 *
 * Authentication data ("scheme" "realm" "user" "password")
 *
 * @par Used with
 *    nua_authenticate()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *    NULL terminated string of format: \n
 *    basic digest scheme:"realm":user:password  \n
 *    @b NOTE the double quotes around realm!
 *    For example: \n
 *	\code Digest:"nokia proxy":xyz:secret \endcode
 *
 * Corresponding tag taking reference parameter is NUTAG_AUTH_REF().
 */
tag_typedef_t nutag_auth = STRTAG_TYPEDEF(auth);

/**@def NUTAG_AUTH_REF(x) 
 * Reference tag for NUTAG_AUTH().
 */


/**@def NUTAG_AUTHTIME(x)
 *
 * Lifetime of authentication data in seconds.
 *
 * @par Used with
 *    Currently not processed by NUA
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    @c 0   Use authentication data only for this handle \n
 *    @c !=0 Lifetime in seconds
 *
 * @todo
 *
 * Corresponding tag taking reference parameter is NUTAG_AUTHTIME_REF().
 */
tag_typedef_t nutag_authtime = INTTAG_TYPEDEF(authtime);

/**@def NUTAG_AUTHTIME_REF(x) 
 * Reference tag for NUTAG_AUTHTIME().
 */



/**@def NUTAG_EVENT(x)
 *
 * NUA event.
 *
 * @deprecated
 *
 * @par Parameter type
 *    enum nua_event_e
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_EVENT_REF().
 */
tag_typedef_t nutag_event = INTTAG_TYPEDEF(event);

/**@def NUTAG_EVENT_REF(x) 
 * Reference tag for NUTAG_EVENT().
 */


/**@def NUTAG_STATUS(x)
 *
 * Response status code
 *
 * @deprecated
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 * 100 - preliminary response, request is being processed by next hop \n
 * 1XX - preliminary response, request is being processed by UAS \n
 * 2XX - successful final response \n
 * 3XX - redirection error response \n
 * 4XX - client error response \n
 * 5XX - server error response \n
 * 6XX - global error response \n
 *
 * Corresponding tag taking reference parameter is NUTAG_STATUS_REF().
 */
tag_typedef_t nutag_status = INTTAG_TYPEDEF(status);

/**@def NUTAG_STATUS_REF(x) 
 * Reference tag for NUTAG_STATUS().
 */


/**@def NUTAG_PHRASE(x)
 *
 * Response phrase
 *
 * @deprecated
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values.
 *
 * Corresponding tag taking reference parameter is NUTAG_PHRASE_REF().
 */
tag_typedef_t nutag_phrase = STRTAG_TYPEDEF(phrase);

/**@def NUTAG_PHRASE_REF(x) 
 * Reference tag for NUTAG_PHRASE().
 */


/**@def NUTAG_HANDLE(x)
 *
 * NUA Handle
 *
 * @deprecated
 *
 * @par Parameter type
 *    nua_handle_t *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_HANDLE_REF().
 */
tag_typedef_t nutag_handle = PTRTAG_TYPEDEF(handle);

/**@def NUTAG_HANDLE_REF(x) 
 * Reference tag for NUTAG_HANDLE().
 */


/**@def NUTAG_NOTIFY_REFER(x)
 *
 * Refer reply handle (used with refer)
 *
 * When making a call in response to a REFER request [RFC3515] with
 * nua_invite(), the application can ask NUA to automatically generate
 * notifications about the call progress to the referrer. In order to
 * do that the application should pass to the stack the handle, which
 * it used to receive the REFER request. It should also pass the event
 * header object along with the handle using NUTAG_REFER_EVENT().
 *
 * @par Used with
 *    nua_invite()
 *
 * @par Parameter type
 *    nua_handle_t *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_NOTIFY_REFER_REF().
 */
tag_typedef_t nutag_notify_refer = PTRTAG_TYPEDEF(notify_refer);

/**@def NUTAG_NOTIFY_REFER_REF(x) 
 * Reference tag for NUTAG_NOTIFY_REFER().
 */

/**@def NUTAG_REFER_EVENT(x)
 *
 * Event used with automatic refer notifications.
 *
 * When creating a call in response to a REFER request [RFC3515]
 * the application can ask NUA to automatically generate notifications
 * about the call progress to the referrer. The #nua_i_refer event will
 * contain a suitable SIP event header for the notifications in the
 * NUTAG_REFER_EVENT() tag. The application should store the SIP event
 * header and when it makes the referred call, it should pass it back
 * to the stack again using the NUTAG_REFER_EVENT() tag.
 *
 * @par Used with
 *
 * @par Parameter type
 *    sip_event_t *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_REFER_EVENT_REF().
 */
tag_typedef_t nutag_refer_event = SIPHDRTAG_NAMED_TYPEDEF(refer_event, event);

/**@def NUTAG_REFER_EVENT_REF(x) 
 * Reference tag for NUTAG_REFER_EVENT().
 */


/**@def NUTAG_REFER_PAUSE()
 *
 * Invite pauses referrer's handle.
 *
 * When creating a call in response to a REFER [RFC3515] request,
 * the application can ask that the original call will be muted
 * when the new call is connected by specifying NUTAG_REFER_PAUSE()
 * along with NUTAG_NOTIFY_REFER() as a parameter to nua_invite() call.
 *
 * @par Used with
 *    nua_invite()
 *
 * @par Parameter type
 *    int
 *
 * @par Values
 *    @c 0   False \n
 *    @c !=0 True
 *
 * Corresponding tag taking reference parameter is NUTAG_REFER_PAUSE_REF().
 *
 * @deprecated Not implemented.
 */
tag_typedef_t nutag_refer_pause = BOOLTAG_TYPEDEF(refer_pause);

/**@def NUTAG_REFER_PAUSE_REF(x) 
 * Reference tag for NUTAG_REFER_PAUSE().
 */


/**@def NUTAG_USER_AGENT()
 *
 * User-Agent string.
 *
 * Indicate the User-Agent header used by the stack. The value set with this
 * tag is concatenated with the value indicating the stack name and version,
 * e.g., "sofia-sip/1.12.1" unless the stack name "sofia-sip" followed by
 * slash is alr