← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/pjsip/include/pjsip/sip_transaction.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/pjsip/include/pjsip/sip_transaction.h
 
1
/* $Id: sip_transaction.h 4420 2013-03-05 11:59:54Z bennylp $ */
 
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
 * @param key       The key string to find the transaction.
 
183
 * @param lock      If non-zero, transaction will be locked before the
 
184
 *                  function returns, to make sure that it's not deleted
 
185
 *                  by other threads.
 
186
 *
 
187
 * @return          The matching transaction instance, or NULL if transaction
 
188
 *                  can not be found.
 
189
 */
 
190
PJ_DECL(pjsip_transaction*) pjsip_tsx_layer_find_tsx( const pj_str_t *key,
 
191
                                                      pj_bool_t lock );
 
192
 
 
193
/**
 
194
 * Create, initialize, and register a new transaction as UAC from the 
 
195
 * specified transmit data (\c tdata). The transmit data must have a valid
 
196
 * \c Request-Line and \c CSeq header. 
 
197
 *
 
198
 * If \c Via header does not exist, it will be created along with a unique
 
199
 * \c branch parameter. If it exists and contains branch parameter, then
 
200
 * the \c branch parameter will be used as is as the transaction key. If
 
201
 * it exists but branch parameter doesn't exist, a unique branch parameter
 
202
 * will be created.
 
203
 *
 
204
 * @param tsx_user  Module to be registered as transaction user of the new
 
205
 *                  transaction, which will receive notification from the
 
206
 *                  transaction via on_tsx_state() callback.
 
207
 * @param tdata     The outgoing request message.
 
208
 * @param p_tsx     On return will contain the new transaction instance.
 
209
 *
 
210
 * @return          PJ_SUCCESS if successfull.
 
211
 */
 
212
PJ_DECL(pj_status_t) pjsip_tsx_create_uac( pjsip_module *tsx_user,
 
213
                                           pjsip_tx_data *tdata,
 
214
                                           pjsip_transaction **p_tsx);
 
215
 
 
216
/**
 
217
 * Variant of pjsip_tsx_create_uac() with additional parameter to specify
 
218
 * the group lock to use. Group lock can be used to synchronize locking
 
219
 * among several objects to prevent deadlock, and to synchronize the
 
220
 * lifetime of objects sharing the same group lock.
 
221
 *
 
222
 * See pjsip_tsx_create_uac() for general info about this function.
 
223
 *
 
224
 * @param tsx_user  Module to be registered as transaction user of the new
 
225
 *                  transaction, which will receive notification from the
 
226
 *                  transaction via on_tsx_state() callback.
 
227
 * @param tdata     The outgoing request message.
 
228
 * @param grp_lock  Optional group lock to use by this transaction. If
 
229
 *                  the value is NULL, the transaction will create its
 
230
 *                  own group lock.
 
231
 * @param p_tsx     On return will contain the new transaction instance.
 
232
 *
 
233
 * @return          PJ_SUCCESS if successfull.
 
234
 */
 
235
PJ_DECL(pj_status_t) pjsip_tsx_create_uac2(pjsip_module *tsx_user,
 
236
                                           pjsip_tx_data *tdata,
 
237
                                           pj_grp_lock_t *grp_lock,
 
238
                                           pjsip_transaction **p_tsx);
 
239
 
 
240
/**
 
241
 * Create, initialize, and register a new transaction as UAS from the
 
242
 * specified incoming request in \c rdata. After calling this function,
 
243
 * application MUST call #pjsip_tsx_recv_msg() so that transaction
 
244
 * moves from state NULL.
 
245
 *
 
246
 * @param tsx_user  Module to be registered as transaction user of the new
 
247
 *                  transaction, which will receive notification from the
 
248
 *                  transaction via on_tsx_state() callback.
 
249
 * @param rdata     The received incoming request.
 
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_uas( pjsip_module *tsx_user,
 
255
                                           pjsip_rx_data *rdata,
 
256
                                           pjsip_transaction **p_tsx );
 
257
 
 
258
/**
 
259
 * Variant of pjsip_tsx_create_uas() with additional parameter to specify
 
260
 * the group lock to use. Group lock can be used to synchronize locking
 
261
 * among several objects to prevent deadlock, and to synchronize the
 
262
 * lifetime of objects sharing the same group lock.
 
263
 *
 
264
 * See pjsip_tsx_create_uas() for general info about this function.
 
265
 *
 
266
 * @param tsx_user  Module to be registered as transaction user of the new
 
267
 *                  transaction, which will receive notification from the
 
268
 *                  transaction via on_tsx_state() callback.
 
269
 * @param rdata     The received incoming request.
 
270
 * @param grp_lock  Optional group lock to use by this transaction. If
 
271
 *                  the value is NULL, the transaction will create its
 
272
 *                  own group lock.
 
273
 * @param p_tsx     On return will contain the new transaction instance.
 
274
 *
 
275
 * @return          PJ_SUCCESS if successfull.
 
276
 */
 
277
PJ_DECL(pj_status_t) pjsip_tsx_create_uas2(pjsip_module *tsx_user,
 
278
                                           pjsip_rx_data *rdata,
 
279
                                           pj_grp_lock_t *grp_lock,
 
280
                                           pjsip_transaction **p_tsx );
 
281
 
 
282
/**
 
283
 * Lock/bind transaction to a specific transport/listener. This is optional,
 
284
 * as normally transport will be selected automatically based on the 
 
285
 * destination of the message upon resolver completion.
 
286
 *
 
287
 * @param tsx       The transaction.
 
288
 * @param sel       Transport selector containing the specification of
 
289
 *                  transport or listener to be used by this transaction
 
290
 *                  to send requests.
 
291
 *
 
292
 * @return          PJ_SUCCESS on success, or the appropriate error code.
 
293
 */
 
294
PJ_DECL(pj_status_t) pjsip_tsx_set_transport(pjsip_transaction *tsx,
 
295
                                             const pjsip_tpselector *sel);
 
296
 
 
297
/**
 
298
 * Call this function to manually feed a message to the transaction.
 
299
 * For UAS transaction, application MUST call this function after
 
300
 * UAS transaction has been created.
 
301
 *
 
302
 * This function SHOULD only be called to pass initial request message
 
303
 * to UAS transaction. Before this function returns, on_tsx_state()
 
304
 * callback of the transaction user will be called. If response message
 
305
 * is passed to this function, then on_rx_response() will also be called
 
306
 * before on_tsx_state().
 
307
 *
 
308
 * @param tsx       The transaction.
 
309
 * @param rdata     The message.
 
310
 */
 
311
PJ_DECL(void) pjsip_tsx_recv_msg( pjsip_transaction *tsx, 
 
312
                                  pjsip_rx_data *rdata);
 
313
 
 
314
/**
 
315
 * Transmit message in tdata with this transaction. It is possible to
 
316
 * pass NULL in tdata for UAC transaction, which in this case the last 
 
317
 * message transmitted, or the request message which was specified when
 
318
 * calling #pjsip_tsx_create_uac(), will be sent.
 
319
 *
 
320
 * This function decrements the reference counter of the transmit buffer
 
321
 * only when it returns PJ_SUCCESS;
 
322
 *
 
323
 * @param tsx       The transaction.
 
324
 * @param tdata     The outgoing message. If NULL is specified, then the
 
325
 *                  last message transmitted (or the message specified 
 
326
 *                  in UAC initialization) will be sent.
 
327
 *
 
328
 * @return          PJ_SUCCESS if successfull.
 
329
 */
 
330
PJ_DECL(pj_status_t) pjsip_tsx_send_msg( pjsip_transaction *tsx,
 
331
                                         pjsip_tx_data *tdata);
 
332
 
 
333
 
 
334
/**
 
335
 * Manually retransmit the last message transmitted by this transaction,
 
336
 * without updating the transaction state. This function is useful when
 
337
 * TU wants to maintain the retransmision by itself (for example,
 
338
 * retransmitting reliable provisional response).
 
339
 *
 
340
 * @param tsx       The transaction.
 
341
 * @param tdata     The outgoing message. If NULL is specified, then the
 
342
 *                  last message transmitted (or the message specified 
 
343
 *                  in UAC initialization) will be sent.
 
344
 *
 
345
 *
 
346
 * @return          PJ_SUCCESS if successful.
 
347
 */
 
348
PJ_DECL(pj_status_t) pjsip_tsx_retransmit_no_state(pjsip_transaction *tsx,
 
349
                                                   pjsip_tx_data *tdata);
 
350
 
 
351
 
 
352
/**
 
353
 * Create transaction key, which is used to match incoming requests 
 
354
 * or response (retransmissions) against transactions.
 
355
 *
 
356
 * @param pool      The pool
 
357
 * @param key       Output key.
 
358
 * @param role      The role of the transaction.
 
359
 * @param method    The method to be put as a key. 
 
360
 * @param rdata     The received data to calculate.
 
361
 *
 
362
 * @return          PJ_SUCCESS or the appropriate error code.
 
363
 */
 
364
PJ_DECL(pj_status_t) pjsip_tsx_create_key( pj_pool_t *pool,
 
365
                                           pj_str_t *key,
 
366
                                           pjsip_role_e role,
 
367
                                           const pjsip_method *method,
 
368
                                           const pjsip_rx_data *rdata );
 
369
 
 
370
/**
 
371
 * Force terminate transaction.
 
372
 *
 
373
 * @param tsx       The transaction.
 
374
 * @param code      The status code to report.
 
375
 */
 
376
PJ_DECL(pj_status_t) pjsip_tsx_terminate( pjsip_transaction *tsx,
 
377
                                          int code );
 
378
 
 
379
 
 
380
/**
 
381
 * Cease retransmission on the UAC transaction. The UAC transaction is
 
382
 * still considered running, and it will complete when either final
 
383
 * response is received or the transaction times out.
 
384
 *
 
385
 * This operation normally is used for INVITE transaction only, when
 
386
 * the transaction is cancelled before any provisional response has been
 
387
 * received.
 
388
 *
 
389
 * @param tsx       The transaction.
 
390
 *
 
391
 * @return          PJ_SUCCESS or the appropriate error code.
 
392
 */
 
393
PJ_DECL(pj_status_t) pjsip_tsx_stop_retransmit(pjsip_transaction *tsx);
 
394
 
 
395
 
 
396
/**
 
397
 * Start a timer to terminate transaction after the specified time
 
398
 * has elapsed. This function is only valid for INVITE transaction,
 
399
 * and only before final response is received for the INVITE transaction.
 
400
 * It is normally called after the UAC has sent CANCEL for this
 
401
 * INVITE transaction. 
 
402
 *
 
403
 * The purpose of this function is to terminate the transaction if UAS 
 
404
 * does not send final response to this INVITE transaction even after 
 
405
 * it sends 200/OK to CANCEL (for example when the UAS complies to RFC
 
406
 * 2543).
 
407
 *
 
408
 * Once this timer is set, the transaction will be terminated either when
 
409
 * a final response is received or the timer expires.
 
410
 *
 
411
 * @param tsx       The transaction.
 
412
 * @param millisec  Timeout value in milliseconds.
 
413
 *
 
414
 * @return          PJ_SUCCESS or the appropriate error code.
 
415
 */
 
416
PJ_DECL(pj_status_t) pjsip_tsx_set_timeout(pjsip_transaction *tsx,
 
417
                                           unsigned millisec);
 
418
 
 
419
 
 
420
/**
 
421
 * Get the transaction instance in the incoming message. If the message
 
422
 * has a corresponding transaction, this function will return non NULL
 
423
 * value.
 
424
 *
 
425
 * @param rdata     The incoming message buffer.
 
426
 *
 
427
 * @return          The transaction instance associated with this message,
 
428
 *                  or NULL if the message doesn't match any transactions.
 
429
 */
 
430
PJ_DECL(pjsip_transaction*) pjsip_rdata_get_tsx( pjsip_rx_data *rdata );
 
431
 
 
432
 
 
433
/**
 
434
 * @}
 
435
 */
 
436
 
 
437
/*
 
438
 * Internal.
 
439
 */
 
440
 
 
441
/*
 
442
 * Dump transaction layer.
 
443
 */
 
444
PJ_DECL(void) pjsip_tsx_layer_dump(pj_bool_t detail);
 
445
 
 
446
/**
 
447
 * Get the string name for the state.
 
448
 * @param state State
 
449
 */
 
450
PJ_DECL(const char *) pjsip_tsx_state_str(pjsip_tsx_state_e state);
 
451
 
 
452
/**
 
453
 * Get the role name.
 
454
 * @param role  Role.
 
455
 */
 
456
PJ_DECL(const char *) pjsip_role_name(pjsip_role_e role);
 
457
 
 
458
 
 
459
PJ_END_DECL
 
460
 
 
461
#endif  /* __PJSIP_TRANSACT_H__ */
 
462