1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJSIP_SIP_TRANSACTION_H__ 21 #define __PJSIP_SIP_TRANSACTION_H__ 22 23 /** 24 * @file sip_transaction.h 25 * @brief SIP Transaction 26 */ 27 28 #include <pjsip/sip_msg.h> 29 #include <pjsip/sip_util.h> 30 #include <pjsip/sip_transport.h> 31 #include <pj/timer.h> 32 33 PJ_BEGIN_DECL 34 35 /** 36 * @defgroup PJSIP_TRANSACT Transaction Layer 37 * @brief Provides statefull message processing. 38 * 39 * This module provides stateful processing to incoming or outgoing SIP 40 * messages. 41 * Before performing any stateful operations, application must register the 42 * transaction layer module by calling #pjsip_tsx_layer_init_module(). 43 * 44 * Application should link with <b>pjsip-core</b> library to 45 * use the transaction layer. 46 */ 47 48 /** 49 * @defgroup PJSIP_TRANSACT_TRANSACTION Transaction 50 * @ingroup PJSIP_TRANSACT 51 * @brief Transaction instance for all types of SIP transactions. 52 * @{ 53 * The pjsip_transaction describes SIP transaction, and is used for 54 * both INVITE and non-INVITE, UAC or UAS. Application must register the 55 * transaction layer module with #pjsip_tsx_layer_init_module() before 56 * performing any stateful operations. 57 */ 58 59 /** 60 * This enumeration represents transaction state. 61 */ 62 typedef enum pjsip_tsx_state_e 63 { 64 PJSIP_TSX_STATE_NULL, /**< For UAC, before any message is sent. */ 65 PJSIP_TSX_STATE_CALLING, /**< For UAC, just after request is sent. */ 66 PJSIP_TSX_STATE_TRYING, /**< For UAS, just after request is received.*/ 67 PJSIP_TSX_STATE_PROCEEDING, /**< For UAS/UAC, after provisional response.*/ 68 PJSIP_TSX_STATE_COMPLETED, /**< For UAS/UAC, after final response. */ 69 PJSIP_TSX_STATE_CONFIRMED, /**< For UAS, after ACK is received. */ 70 PJSIP_TSX_STATE_TERMINATED, /**< For UAS/UAC, before it's destroyed. */ 71 PJSIP_TSX_STATE_DESTROYED, /**< For UAS/UAC, will be destroyed now. */ 72 PJSIP_TSX_STATE_MAX /**< Number of states. */ 73 } pjsip_tsx_state_e; 74 75 76 /** 77 * This structure describes SIP transaction object. The transaction object 78 * is used to handle both UAS and UAC transaction. 79 */ 80 struct pjsip_transaction 81 { 82 /* 83 * Administrivia 84 */ 85 pj_pool_t *pool; /**< Pool owned by the tsx. */ 86 pjsip_module *tsx_user; /**< Transaction user. */ 87 pjsip_endpoint *endpt; /**< Endpoint instance. */ 88 pj_bool_t terminating; /**< terminate() was called */ 89 pj_grp_lock_t *grp_lock; /**< Transaction grp lock. */ 90 pj_mutex_t *mutex_b; /**< Second mutex to avoid 91 deadlock. It is used to 92 protect timer. */ 93 94 /* 95 * Transaction identification. 96 */ 97 char obj_name[PJ_MAX_OBJ_NAME]; /**< Log info. */ 98 pjsip_role_e role; /**< Role (UAS or UAC) */ 99 pjsip_method method; /**< The method. */ 100 pj_int32_t cseq; /**< The CSeq */ 101 pj_str_t transaction_key;/**< Hash table key. */ 102 pj_uint32_t hashed_key; /**< Key's hashed value. */ 103 pj_str_t branch; /**< The branch Id. */ 104 105 /* 106 * State and status. 107 */ 108 int status_code; /**< Last status code seen. */ 109 pj_str_t status_text; /**< Last reason phrase. */ 110 pjsip_tsx_state_e state; /**< State. */ 111 int handle_200resp; /**< UAS 200/INVITE retrsm.*/ 112 int tracing; /**< Tracing enabled? */ 113 114 /** Handler according to current state. */ 115 pj_status_t (*state_handler)(struct pjsip_transaction *, pjsip_event *); 116 117 /* 118 * Transport. 119 */ 120 pjsip_transport *transport; /**< Transport to use. */ 121 pj_bool_t is_reliable; /**< Transport is reliable. */ 122 pj_sockaddr addr; /**< Destination address. */ 123 int addr_len; /**< Address length. */ 124 pjsip_response_addr res_addr; /**< Response address. */ 125 unsigned transport_flag; /**< Miscelaneous flag. */ 126 pj_status_t transport_err; /**< Internal error code. */ 127 pjsip_tpselector tp_sel; /**< Transport selector. */ 128 pjsip_tx_data *pending_tx; /**< Tdata which caused 129 pending transport flag 130 to be set on tsx. */ 131 pjsip_tp_state_listener_key *tp_st_key; /**< Transport state listener 132 key. */ 133 134 /* 135 * Messages and timer. 136 */ 137 pjsip_tx_data *last_tx; /**< Msg kept for retrans. */ 138 int retransmit_count;/**< Retransmission count. */ 139 pj_timer_entry retransmit_timer;/**< Retransmit timer. */ 140 pj_timer_entry timeout_timer; /**< Timeout timer. */ 141 142 /** Module specific data. */ 143 void *mod_data[PJSIP_MAX_MODULE]; 144 }; 145 146 147 /** 148 * Create and register transaction layer module to the specified endpoint. 149 * 150 * @param endpt The endpoint instance. 151 * 152 * @return PJ_SUCCESS on success. 153 */ 154 PJ_DECL(pj_status_t) pjsip_tsx_layer_init_module(pjsip_endpoint *endpt); 155 156 /** 157 * Get the instance of the transaction layer module. 158 * 159 * @return The transaction layer module. 160 */ 161 PJ_DECL(pjsip_module*) pjsip_tsx_layer_instance(void); 162 163 /** 164 * Unregister and destroy transaction layer module. 165 * 166 * @return PJ_SUCCESS on success. 167 */ 168 PJ_DECL(pj_status_t) pjsip_tsx_layer_destroy(void); 169 170 /** 171 * Retrieve the current number of transactions currently registered 172 * in the hash table. 173 * 174 * @return Number of transactions. 175 */ 176 PJ_DECL(unsigned) pjsip_tsx_layer_get_tsx_count(void); 177 178 /** 179 * Find a transaction with the specified key. The transaction key normally 180 * is created by calling #pjsip_tsx_create_key() from an incoming message. 181 * 182 * IMPORTANT: To prevent deadlock, application should use 183 * #pjsip_tsx_layer_find_tsx2() instead which only adds a reference to 184 * the transaction instead of locking it. 185 * 186 * @param key The key string to find the transaction. 187 * @param lock If non-zero, transaction will be locked before the 188 * function returns, to make sure that it's not deleted 189 * by other threads. 190 * 191 * @return The matching transaction instance, or NULL if transaction 192 * can not be found. 193 */ 194 PJ_DECL(pjsip_transaction*) pjsip_tsx_layer_find_tsx( const pj_str_t *key, 195 pj_bool_t lock ); 196 197 /** 198 * Find a transaction with the specified key. The transaction key normally 199 * is created by calling #pjsip_tsx_create_key() from an incoming message. 200 * 201 * @param key The key string to find the transaction. 202 * @param add_ref If non-zero, transaction's reference will be added 203 * by one before the function returns, to make sure that 204 * it's not deleted by other threads. 205 * 206 * @return The matching transaction instance, or NULL if transaction 207 * can not be found. 208 */ 209 PJ_DECL(pjsip_transaction*) pjsip_tsx_layer_find_tsx2( const pj_str_t *key, 210 pj_bool_t add_ref ); 211 212 /** 213 * Create, initialize, and register a new transaction as UAC from the 214 * specified transmit data (\c tdata). The transmit data must have a valid 215 * \c Request-Line and \c CSeq header. 216 * 217 * If \c Via header does not exist, it will be created along with a unique 218 * \c branch parameter. If it exists and contains branch parameter, then 219 * the \c branch parameter will be used as is as the transaction key. If 220 * it exists but branch parameter doesn't exist, a unique branch parameter 221 * will be created. 222 * 223 * @param tsx_user Module to be registered as transaction user of the new 224 * transaction, which will receive notification from the 225 * transaction via on_tsx_state() callback. 226 * @param tdata The outgoing request message. 227 * @param p_tsx On return will contain the new transaction instance. 228 * 229 * @return PJ_SUCCESS if successfull. 230 */ 231 PJ_DECL(pj_status_t) pjsip_tsx_create_uac( pjsip_module *tsx_user, 232 pjsip_tx_data *tdata, 233 pjsip_transaction **p_tsx); 234 235 /** 236 * Variant of pjsip_tsx_create_uac() with additional parameter to specify 237 * the group lock to use. Group lock can be used to synchronize locking 238 * among several objects to prevent deadlock, and to synchronize the 239 * lifetime of objects sharing the same group lock. 240 * 241 * See pjsip_tsx_create_uac() for general info about this function. 242 * 243 * @param tsx_user Module to be registered as transaction user of the new 244 * transaction, which will receive notification from the 245 * transaction via on_tsx_state() callback. 246 * @param tdata The outgoing request message. 247 * @param grp_lock Optional group lock to use by this transaction. If 248 * the value is NULL, the transaction will create its 249 * own group lock. 250 * @param p_tsx On return will contain the new transaction instance. 251 * 252 * @return PJ_SUCCESS if successfull. 253 */ 254 PJ_DECL(pj_status_t) pjsip_tsx_create_uac2(pjsip_module *tsx_user, 255 pjsip_tx_data *tdata, 256 pj_grp_lock_t *grp_lock, 257 pjsip_transaction **p_tsx); 258 259 /** 260 * Create, initialize, and register a new transaction as UAS from the 261 * specified incoming request in \c rdata. After calling this function, 262 * application MUST call #pjsip_tsx_recv_msg() so that transaction 263 * moves from state NULL. 264 * 265 * @param tsx_user Module to be registered as transaction user of the new 266 * transaction, which will receive notification from the 267 * transaction via on_tsx_state() callback. 268 * @param rdata The received incoming request. 269 * @param p_tsx On return will contain the new transaction instance. 270 * 271 * @return PJ_SUCCESS if successfull. 272 */ 273 PJ_DECL(pj_status_t) pjsip_tsx_create_uas( pjsip_module *tsx_user, 274 pjsip_rx_data *rdata, 275 pjsip_transaction **p_tsx ); 276 277 /** 278 * Variant of pjsip_tsx_create_uas() with additional parameter to specify 279 * the group lock to use. Group lock can be used to synchronize locking 280 * among several objects to prevent deadlock, and to synchronize the 281 * lifetime of objects sharing the same group lock. 282 * 283 * See pjsip_tsx_create_uas() for general info about this function. 284 * 285 * @param tsx_user Module to be registered as transaction user of the new 286 * transaction, which will receive notification from the 287 * transaction via on_tsx_state() callback. 288 * @param rdata The received incoming request. 289 * @param grp_lock Optional group lock to use by this transaction. If 290 * the value is NULL, the transaction will create its 291 * own group lock. 292 * @param p_tsx On return will contain the new transaction instance. 293 * 294 * @return PJ_SUCCESS if successfull. 295 */ 296 PJ_DECL(pj_status_t) pjsip_tsx_create_uas2(pjsip_module *tsx_user, 297 pjsip_rx_data *rdata, 298 pj_grp_lock_t *grp_lock, 299 pjsip_transaction **p_tsx ); 300 301 /** 302 * Lock/bind transaction to a specific transport/listener. This is optional, 303 * as normally transport will be selected automatically based on the 304 * destination of the message upon resolver completion. 305 * 306 * @param tsx The transaction. 307 * @param sel Transport selector containing the specification of 308 * transport or listener to be used by this transaction 309 * to send requests. 310 * 311 * @return PJ_SUCCESS on success, or the appropriate error code. 312 */ 313 PJ_DECL(pj_status_t) pjsip_tsx_set_transport(pjsip_transaction *tsx, 314 const pjsip_tpselector *sel); 315 316 /** 317 * Call this function to manually feed a message to the transaction. 318 * For UAS transaction, application MUST call this function after 319 * UAS transaction has been created. 320 * 321 * This function SHOULD only be called to pass initial request message 322 * to UAS transaction. Before this function returns, on_tsx_state() 323 * callback of the transaction user will be called. If response message 324 * is passed to this function, then on_rx_response() will also be called 325 * before on_tsx_state(). 326 * 327 * @param tsx The transaction. 328 * @param rdata The message. 329 */ 330 PJ_DECL(void) pjsip_tsx_recv_msg( pjsip_transaction *tsx, 331 pjsip_rx_data *rdata); 332 333 /** 334 * Transmit message in tdata with this transaction. It is possible to 335 * pass NULL in tdata for UAC transaction, which in this case the last 336 * message transmitted, or the request message which was specified when 337 * calling #pjsip_tsx_create_uac(), will be sent. 338 * 339 * This function decrements the reference counter of the transmit buffer 340 * only when it returns PJ_SUCCESS; 341 * 342 * @param tsx The transaction. 343 * @param tdata The outgoing message. If NULL is specified, then the 344 * last message transmitted (or the message specified 345 * in UAC initialization) will be sent. 346 * 347 * @return PJ_SUCCESS if successfull. 348 */ 349 PJ_DECL(pj_status_t) pjsip_tsx_send_msg( pjsip_transaction *tsx, 350 pjsip_tx_data *tdata); 351 352 353 /** 354 * Manually retransmit the last message transmitted by this transaction, 355 * without updating the transaction state. This function is useful when 356 * TU wants to maintain the retransmision by itself (for example, 357 * retransmitting reliable provisional response). 358 * 359 * @param tsx The transaction. 360 * @param tdata The outgoing message. If NULL is specified, then the 361 * last message transmitted (or the message specified 362 * in UAC initialization) will be sent. 363 * 364 * 365 * @return PJ_SUCCESS if successful. 366 */ 367 PJ_DECL(pj_status_t) pjsip_tsx_retransmit_no_state(pjsip_transaction *tsx, 368 pjsip_tx_data *tdata); 369 370 371 /** 372 * Create transaction key, which is used to match incoming requests 373 * or response (retransmissions) against transactions. 374 * 375 * @param pool The pool 376 * @param key Output key. 377 * @param role The role of the transaction. 378 * @param method The method to be put as a key. 379 * @param rdata The received data to calculate. 380 * 381 * @return PJ_SUCCESS or the appropriate error code. 382 */ 383 PJ_DECL(pj_status_t) pjsip_tsx_create_key( pj_pool_t *pool, 384 pj_str_t *key, 385 pjsip_role_e role, 386 const pjsip_method *method, 387 const pjsip_rx_data *rdata ); 388 389 /** 390 * Force terminate transaction. 391 * 392 * @param tsx The transaction. 393 * @param code The status code to report. 394 */ 395 PJ_DECL(pj_status_t) pjsip_tsx_terminate( pjsip_transaction *tsx, 396 int code ); 397 398 399 /** 400 * Cease retransmission on the UAC transaction. The UAC transaction is 401 * still considered running, and it will complete when either final 402 * response is received or the transaction times out. 403 * 404 * This operation normally is used for INVITE transaction only, when 405 * the transaction is cancelled before any provisional response has been 406 * received. 407 * 408 * @param tsx The transaction. 409 * 410 * @return PJ_SUCCESS or the appropriate error code. 411 */ 412 PJ_DECL(pj_status_t) pjsip_tsx_stop_retransmit(pjsip_transaction *tsx); 413 414 415 /** 416 * Start a timer to terminate transaction after the specified time 417 * has elapsed. This function is only valid for INVITE transaction, 418 * and only before final response is received for the INVITE transaction. 419 * It is normally called after the UAC has sent CANCEL for this 420 * INVITE transaction. 421 * 422 * The purpose of this function is to terminate the transaction if UAS 423 * does not send final response to this INVITE transaction even after 424 * it sends 200/OK to CANCEL (for example when the UAS complies to RFC 425 * 2543). 426 * 427 * Once this timer is set, the transaction will be terminated either when 428 * a final response is received or the timer expires. 429 * 430 * @param tsx The transaction. 431 * @param millisec Timeout value in milliseconds. 432 * 433 * @return PJ_SUCCESS or the appropriate error code. 434 */ 435 PJ_DECL(pj_status_t) pjsip_tsx_set_timeout(pjsip_transaction *tsx, 436 unsigned millisec); 437 438 439 /** 440 * Get the transaction instance in the incoming message. If the message 441 * has a corresponding transaction, this function will return non NULL 442 * value. 443 * 444 * @param rdata The incoming message buffer. 445 * 446 * @return The transaction instance associated with this message, 447 * or NULL if the message doesn't match any transactions. 448 */ 449 PJ_DECL(pjsip_transaction*) pjsip_rdata_get_tsx( pjsip_rx_data *rdata ); 450 451 452 /** 453 * @} 454 */ 455 456 /* 457 * Internal. 458 */ 459 460 /* 461 * Dump transaction layer. 462 */ 463 PJ_DECL(void) pjsip_tsx_layer_dump(pj_bool_t detail); 464 465 /** 466 * Get the string name for the state. 467 * @param state State 468 */ 469 PJ_DECL(const char *) pjsip_tsx_state_str(pjsip_tsx_state_e state); 470 471 /** 472 * Get the role name. 473 * @param role Role. 474 */ 475 PJ_DECL(const char *) pjsip_role_name(pjsip_role_e role); 476 477 478 PJ_END_DECL 479 480 #endif /* __PJSIP_TRANSACT_H__ */ 481 482