Changeset 2370 for pjproject/trunk/pjsip/include/pjsip/sip_util.h
- Timestamp:
- Nov 27, 2008 12:06:46 AM (15 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/trunk/pjsip/include/pjsip/sip_util.h
r2039 r2370 25 25 26 26 PJ_BEGIN_DECL 27 28 /** 29 * @defgroup PJSIP_ENDPT_TARGET_URI Target URI Management 30 * @ingroup PJSIP_CORE_CORE 31 * @brief Management of target URI's in case of redirection 32 * @{ 33 * This module provides utility functions to manage target set for UAC. 34 * The target set is provided as pjsip_target_set structure. Initially, 35 * the target set for UAC contains only one target, that is the target of 36 * the initial request. When 3xx/redirection class response is received, 37 * the UAC can use the functionality of this module to add the URI's listed 38 * in the Contact header(s) in the response to the target set, and retry 39 * sending the request to the next destination/target. The UAC may retry 40 * this sequentially until one of the target answers with succesful/2xx 41 * response, or one target returns global error/6xx response, or all targets 42 * are exhausted. 43 * 44 * This module is currently used by the \ref PJSIP_INV. 45 */ 46 47 /** 48 * This structure describes a target, which can be chained together to form 49 * a target set. Each target contains an URI, priority (as q-value), and 50 * the last status code and reason phrase received from the target, if the 51 * target has been contacted. If the target has not been contacted, the 52 * status code field will be zero. 53 */ 54 typedef struct pjsip_target 55 { 56 PJ_DECL_LIST_MEMBER(struct pjsip_target);/**< Standard list element */ 57 pjsip_uri *uri; /**< The target URI */ 58 int q1000; /**< q-value multiplied by 1000 */ 59 pjsip_status_code code; /**< Last status code received */ 60 pj_str_t reason; /**< Last reason phrase received */ 61 } pjsip_target; 62 63 64 /** 65 * This describes a target set. A target set contains a linked-list of 66 * pjsip_target. 67 */ 68 typedef struct pjsip_target_set 69 { 70 pjsip_target head; /**< Target linked-list head */ 71 pjsip_target *current; /**< Current target. */ 72 } pjsip_target_set; 73 74 75 /** 76 * These enumerations specify the action to be performed to a redirect 77 * response. 78 */ 79 typedef enum pjsip_redirect_op 80 { 81 /** 82 * Reject the redirection to the current target. The UAC will 83 * select the next target from the target set if exists. 84 */ 85 PJSIP_REDIRECT_REJECT, 86 87 /** 88 * Accept the redirection to the current target. The INVITE request 89 * will be resent to the current target. 90 */ 91 PJSIP_REDIRECT_ACCEPT, 92 93 /** 94 * Defer the redirection decision, for example to request permission 95 * from the end user. 96 */ 97 PJSIP_REDIRECT_PENDING, 98 99 /** 100 * Stop the whole redirection process altogether. This will cause 101 * the invite session to be disconnected. 102 */ 103 PJSIP_REDIRECT_STOP 104 105 } pjsip_redirect_op; 106 107 108 /** 109 * Initialize target set. This will empty the list of targets in the 110 * target set. 111 * 112 * @param tset The target set. 113 */ 114 PJ_INLINE(void) pjsip_target_set_init(pjsip_target_set *tset) 115 { 116 pj_list_init(&tset->head); 117 tset->current = NULL; 118 } 119 120 121 /** 122 * Add an URI to the target set, if the URI is not already in the target set. 123 * The URI comparison rule of pjsip_uri_cmp() will be used to determine the 124 * equality of this URI compared to existing URI's in the target set. The 125 * URI will be cloned using the specified memory pool before it is added to 126 * the list. 127 * 128 * The first URI added to the target set will also be made current target 129 * by this function. 130 * 131 * @param tset The target set. 132 * @param pool The memory pool to be used to duplicate the URI. 133 * @param uri The URI to be checked and added. 134 * @param q1000 The q-value multiplied by 1000. 135 * 136 * @return PJ_SUCCESS if the URI was added to the target set, 137 * or PJ_EEXISTS if the URI already exists in the target 138 * set, or other error codes. 139 */ 140 PJ_DECL(pj_status_t) pjsip_target_set_add_uri(pjsip_target_set *tset, 141 pj_pool_t *pool, 142 const pjsip_uri *uri, 143 int q1000); 144 145 /** 146 * Extract URI's in the Contact headers of the specified (response) message 147 * and add them to the target set. This function will also check if the 148 * URI's already exist in the target set before adding them to the list. 149 * 150 * @param tset The target set. 151 * @param pool The memory pool to be used to duplicate the URI's. 152 * @param msg SIP message from which the Contact headers will be 153 * scanned and the URI's to be extracted, checked, and 154 * added to the target set. 155 * 156 * @return PJ_SUCCESS if at least one URI was added to the 157 * target set, or PJ_EEXISTS if all URI's in the message 158 * already exists in the target set or if the message 159 * doesn't contain usable Contact headers, or other error 160 * codes. 161 */ 162 PJ_DECL(pj_status_t) pjsip_target_set_add_from_msg(pjsip_target_set *tset, 163 pj_pool_t *pool, 164 const pjsip_msg *msg); 165 166 /** 167 * Get the next target to be retried. This function will scan the target set 168 * for target which hasn't been tried, and return one target with the 169 * highest q-value, if such target exists. This function will return NULL 170 * if there is one target with 2xx or 6xx code or if all targets have been 171 * tried. 172 * 173 * @param tset The target set. 174 * 175 * @return The next target to be tried, or NULL if all targets have 176 * been tried or at least one target returns 2xx or 6xx 177 * response. 178 */ 179 PJ_DECL(pjsip_target*) 180 pjsip_target_set_get_next(const pjsip_target_set *tset); 181 182 183 /** 184 * Set the specified target as the current target in the target set. The 185 * current target may be used by application to keep track on which target 186 * is currently being operated on. 187 * 188 * @param tset The target set. 189 * @param target The target to be set as current target. 190 * 191 * @return PJ_SUCCESS or the appropriate error code. 192 */ 193 PJ_DECL(pj_status_t) pjsip_target_set_set_current(pjsip_target_set *tset, 194 pjsip_target *target); 195 196 197 /** 198 * Set the status code and reason phrase of the specified target. 199 * 200 * @param target The target. 201 * @param pool The memory pool to be used to duplicate the reason phrase. 202 * @param code The SIP status code to be set to the target. 203 * @param reason The reason phrase to be set to the target. 204 * 205 * @return PJ_SUCCESS on successful operation or the appropriate 206 * error code. 207 */ 208 PJ_DECL(pj_status_t) pjsip_target_assign_status(pjsip_target *target, 209 pj_pool_t *pool, 210 int status_code, 211 const pj_str_t *reason); 212 213 /** 214 * @} 215 */ 27 216 28 217 /**
Note: See TracChangeset
for help on using the changeset viewer.