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