Target URI Management
[At the Very Core]

---

Detailed Description

This module is currently used by the INVITE Session.

Data Structures
struct	pjsip_target
struct	pjsip_target_set
Enumerations
enum	pjsip_redirect_op { PJSIP_REDIRECT_REJECT, PJSIP_REDIRECT_ACCEPT, 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)

---

Enumeration Type Documentation

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_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

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 PJ_INLINE, and pj_list_init().

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.

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* 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.

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.

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.
	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.