Target URI Management

Management of target URI's in case of redirectionThis module provides utility functions to manage target set for UAC. The target set is provided as pjsip_target_set structure. Initially, the target set for UAC contains only one target, that is the target of the initial request. When 3xx/redirection class response is received, the UAC can use the functionality of this module to add the URI's listed in the Contact header(s) in the response to the target set, and retry sending the request to the next destination/target. The UAC may retry this sequentially until one of the target answers with succesful/2xx response, or one target returns global error/6xx response, or all targets are exhausted. More...

Data Structures
struct	pjsip_target
struct	pjsip_target_set

Enumerations
enum	pjsip_redirect_op {   PJSIP_REDIRECT_REJECT , PJSIP_REDIRECT_ACCEPT , PJSIP_REDIRECT_ACCEPT_REPLACE , PJSIP_REDIRECT_PENDING ,   PJSIP_REDIRECT_STOP }

Functions
void	pjsip_target_set_init (pjsip_target_set *tset)
pj_status_t	pjsip_target_set_add_uri (pjsip_target_set *tset, pj_pool_t *pool, const pjsip_uri *uri, int q1000)
pj_status_t	pjsip_target_set_add_from_msg (pjsip_target_set *tset, pj_pool_t *pool, const pjsip_msg *msg)
pjsip_target *	pjsip_target_set_get_next (const pjsip_target_set *tset)
pj_status_t	pjsip_target_set_set_current (pjsip_target_set *tset, pjsip_target *target)
pj_status_t	pjsip_target_assign_status (pjsip_target *target, pj_pool_t *pool, int status_code, const pj_str_t *reason)

Detailed Description

This module is currently used by the INVITE Session.

Enumeration Type Documentation

pjsip_redirect_op

enum pjsip_redirect_op

These enumerations specify the action to be performed to a redirect response.

Enumerator
PJSIP_REDIRECT_REJECT	Reject the redirection to the current target. The UAC will select the next target from the target set if exists.
PJSIP_REDIRECT_ACCEPT	Accept the redirection to the current target. The INVITE request will be resent to the current target.
PJSIP_REDIRECT_ACCEPT_REPLACE	Accept the redirection to the current target and replace the To header in the INVITE request with the current target. The INVITE request will be resent to the current target.
PJSIP_REDIRECT_PENDING	Defer the redirection decision, for example to request permission from the end user.
PJSIP_REDIRECT_STOP	Stop the whole redirection process altogether. This will cause the invite session to be disconnected.

Function Documentation

pjsip_target_set_init()

void pjsip_target_set_init

(

pjsip_target_set *

tset

)

Initialize target set. This will empty the list of targets in the target set.

Parameters

tset	The target set.

References pjsip_target_set::current, pjsip_target_set::head, PJ_INLINE, and pj_list_init().

pjsip_target_set_add_uri()

pj_status_t pjsip_target_set_add_uri	(	pjsip_target_set *	tset,
		pj_pool_t *	pool,
		const pjsip_uri *	uri,
		int	q1000
	)

Add an URI to the target set, if the URI is not already in the target set. The URI comparison rule of pjsip_uri_cmp() will be used to determine the equality of this URI compared to existing URI's in the target set. The URI will be cloned using the specified memory pool before it is added to the list.

The first URI added to the target set will also be made current target by this function.

Parameters

tset	The target set.
pool	The memory pool to be used to duplicate the URI.
uri	The URI to be checked and added.
q1000	The q-value multiplied by 1000.

Returns

PJ_SUCCESS if the URI was added to the target set, or PJ_EEXISTS if the URI already exists in the target set, or other error codes.

pjsip_target_set_add_from_msg()

pj_status_t pjsip_target_set_add_from_msg	(	pjsip_target_set *	tset,
		pj_pool_t *	pool,
		const pjsip_msg *	msg
	)

Extract URI's in the Contact headers of the specified (response) message and add them to the target set. This function will also check if the URI's already exist in the target set before adding them to the list.

Parameters

tset	The target set.
pool	The memory pool to be used to duplicate the URI's.
msg	SIP message from which the Contact headers will be scanned and the URI's to be extracted, checked, and added to the target set.

Returns

PJ_SUCCESS if at least one URI was added to the target set, or PJ_EEXISTS if all URI's in the message already exists in the target set or if the message doesn't contain usable Contact headers, or other error codes.

pjsip_target_set_get_next()

pjsip_target * pjsip_target_set_get_next

(

const pjsip_target_set *

tset

)

Get the next target to be retried. This function will scan the target set for target which hasn't been tried, and return one target with the highest q-value, if such target exists. This function will return NULL if there is one target with 2xx or 6xx code or if all targets have been tried.

Parameters

tset	The target set.

Returns

The next target to be tried, or NULL if all targets have been tried or at least one target returns 2xx or 6xx response.

pjsip_target_set_set_current()

pj_status_t pjsip_target_set_set_current	(	pjsip_target_set *	tset,
		pjsip_target *	target
	)

Set the specified target as the current target in the target set. The current target may be used by application to keep track on which target is currently being operated on.

Parameters

tset	The target set.
target	The target to be set as current target.

Returns

PJ_SUCCESS or the appropriate error code.

pjsip_target_assign_status()

pj_status_t pjsip_target_assign_status	(	pjsip_target *	target,
		pj_pool_t *	pool,
		int	status_code,
		const pj_str_t *	reason
	)

Set the status code and reason phrase of the specified target.

Parameters

target	The target.
pool	The memory pool to be used to duplicate the reason phrase.
status_code	The SIP status code to be set to the target.
reason	The reason phrase to be set to the target.

Returns

PJ_SUCCESS on successful operation or the appropriate error code.