Group PJSIP_ENDPT_TARGET_URI

group PJSIP_ENDPT_TARGET_URI

Management of target URI’s in case of redirection

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

This module is currently used by the INVITE Session.

Enums

enum pjsip_redirect_op

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

Values:

enumerator PJSIP_REDIRECT_REJECT

Reject the redirection to the current target. The UAC will select the next target from the target set if exists.

enumerator PJSIP_REDIRECT_ACCEPT

Accept the redirection to the current target. The INVITE request will be resent to the current target.

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

enumerator PJSIP_REDIRECT_PENDING

Defer the redirection decision, for example to request permission from the end user.

enumerator PJSIP_REDIRECT_STOP

Stop the whole redirection process altogether. This will cause the invite session to be disconnected.

Functions

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.

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.

struct pjsip_target
#include <sip_util.h>

This structure describes a target, which can be chained together to form a target set. Each target contains an URI, priority (as q-value), and the last status code and reason phrase received from the target, if the target has been contacted. If the target has not been contacted, the status code field will be zero.

struct pjsip_target_set
#include <sip_util.h>

This describes a target set. A target set contains a linked-list of pjsip_target.