← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjsip/include/pjsip/sip_transaction.h
 
1
/* $Id: sip_transaction.h 3553 2011-05-05 06:14:19Z nanang $ */
 
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_mutex_t                 *mutex;          /**< Mutex for this tsx.    */
 
89
    pj_mutex_t                 *mutex_b;        /**< Second mutex to avoid
 
90
                                                     deadlock. It is used to
 
91
                                                     protect timer.         */
 
92
 
 
93
    /*
 
94
     * Transaction identification.
 
95
     */
 
96
    char                        obj_name[PJ_MAX_OBJ_NAME];  /**< Log info.  */
 
97
    pjsip_role_e                role;           /**< Role (UAS or UAC)      */
 
98
    pjsip_method                method;         /**< The method.            */
 
99
    pj_int32_t                  cseq;           /**< The CSeq               */
 
100
    pj_str_t                    transaction_key;/**< Hash table key.        */
 
101
    pj_uint32_t                 hashed_key;     /**< Key's hashed value.    */
 
102
    pj_str_t                    branch;         /**< The branch Id.         */
 
103
 
 
104
    /*
 
105
     * State and status.
 
106
     */
 
107
    int                         status_code;    /**< Last status code seen. */
 
108
    pj_str_t                    status_text;    /**< Last reason phrase.    */
 
109
    pjsip_tsx_state_e           state;          /**< State.                 */
 
110
    int                         handle_200resp; /**< UAS 200/INVITE  retrsm.*/
 
111
    int                         tracing;        /**< Tracing enabled?       */
 
112
 
 
113
    /** Handler according to current state. */
 
114
    pj_status_t (*state_handler)(struct pjsip_transaction *, pjsip_event *);
 
115
 
 
116
    /*
 
117
     * Transport.
 
118
     */
 
119
    pjsip_transport            *transport;      /**< Transport to use.      */
 
120
    pj_bool_t                   is_reliable;    /**< Transport is reliable. */
 
121
    pj_sockaddr                 addr;           /**< Destination address.   */
 
122
    int                         addr_len;       /**< Address length.        */
 
123
    pjsip_response_addr         res_addr;       /**< Response address.      */
 
124
    unsigned                    transport_flag; /**< Miscelaneous flag.     */
 
125
    pj_status_t                 transport_err;  /**< Internal error code.   */
 
126
    pjsip_tpselector            tp_sel;         /**< Transport selector.    */
 
127
    pjsip_tx_data              *pending_tx;     /**< Tdata which caused
 
128
                                                     pending transport flag
 
129
                                                     to be set on tsx.      */
 
130
    pjsip_tp_state_listener_key *tp_st_key;     /**< Transport state listener
 
131
                                                     key.                   */
 
132
 
 
133
    /*
 
134
     * Messages and timer.
 
135
     */
 
136
    pjsip_tx_data              *last_tx;        /**< Msg kept for retrans.  */
 
137
    int                         retransmit_count;/**< Retransmission count. */
 
138
    pj_timer_entry              retransmit_timer;/**< Retransmit timer.     */
 
139
    pj_timer_entry              timeout_timer;  /**< Timeout timer.         */
 
140
 
 
141
    /** Module specific data. */
 
142
    void                       *mod_data[PJSIP_MAX_MODULE];
 
143
};
 
144
 
 
145
 
 
146
/**
 
147
 * Create and register transaction layer module to the specified endpoint.
 
148
 *
 
149
 * @param endpt     The endpoint instance.
 
150
 *
 
151
 * @return          PJ_SUCCESS on success.
 
152
 */
 
153
PJ_DECL(pj_status_t) pjsip_tsx_layer_init_module(pjsip_endpoint *endpt);
 
154
 
 
155
/**
 
156
 * Get the instance of the transaction layer module.
 
157
 *
 
158
 * @return          The transaction layer module.
 
159
 */
 
160
PJ_DECL(pjsip_module*) pjsip_tsx_layer_instance(void);
 
161
 
 
162
/**
 
163
 * Unregister and destroy transaction layer module.
 
164
 *
 
165
 * @return          PJ_SUCCESS on success.
 
166
 */
 
167
PJ_DECL(pj_status_t) pjsip_tsx_layer_destroy(void);
 
168
 
 
169
/**
 
170
 * Retrieve the current number of transactions currently registered
 
171
 * in the hash table.
 
172
 *
 
173
 * @return          Number of transactions.
 
174
 */
 
175
PJ_DECL(unsigned) pjsip_tsx_layer_get_tsx_count(void);
 
176
 
 
177
/**
 
178
 * Find a transaction with the specified key. The transaction key normally
 
179
 * is created by calling #pjsip_tsx_create_key() from an incoming message.
 
180
 *
 
181
 * @param key       The key string to find the transaction.
 
182
 * @param lock      If non-zero, transaction will be locked before the
 
183
 *                  function returns, to make sure that it's not deleted
 
184
 *                  by other threads.
 
185
 *
 
186
 * @return          The matching transaction instance, or NULL if transaction
 
187
 *                  can not be found.
 
188
 */
 
189
PJ_DECL(pjsip_transaction*) pjsip_tsx_layer_find_tsx( const pj_str_t *key,
 
190
                                                      pj_bool_t lock );
 
191
 
 
192
/**
 
193
 * Create, initialize, and register a new transaction as UAC from the 
 
194
 * specified transmit data (\c tdata). The transmit data must have a valid
 
195
 * \c Request-Line and \c CSeq header. 
 
196
 *
 
197
 * If \c Via header does not exist, it will be created along with a unique
 
198
 * \c branch parameter. If it exists and contains branch parameter, then
 
199
 * the \c branch parameter will be used as is as the transaction key. If
 
200
 * it exists but branch parameter doesn't exist, a unique branch parameter
 
201
 * will be created.
 
202
 *
 
203
 * @param tsx_user  Module to be registered as transaction user of the new
 
204
 *                  transaction, which will receive notification from the
 
205
 *                  transaction via on_tsx_state() callback.
 
206
 * @param tdata     The outgoing request message.
 
207
 * @param p_tsx     On return will contain the new transaction instance.
 
208
 *
 
209
 * @return          PJ_SUCCESS if successfull.
 
210
 */
 
211
PJ_DECL(pj_status_t) pjsip_tsx_create_uac( pjsip_module *tsx_user,
 
212
                                           pjsip_tx_data *tdata,
 
213
                                           pjsip_transaction **p_tsx);
 
214
 
 
215
/**
 
216
 * Create, initialize, and register a new transaction as UAS from the
 
217
 * specified incoming request in \c rdata. After calling this function,
 
218
 * application MUST call #pjsip_tsx_recv_msg() so that transaction
 
219
 * moves from state NULL.
 
220
 *
 
221
 * @param tsx_user  Module to be registered as transaction user of the new
 
222
 *                  transaction, which will receive notification from the
 
223
 *                  transaction via on_tsx_state() callback.
 
224
 * @param rdata     The received incoming request.
 
225
 * @param p_tsx     On return will contain the new transaction instance.
 
226
 *
 
227
 * @return          PJ_SUCCESS if successfull.
 
228
 */
 
229
PJ_DECL(pj_status_t) pjsip_tsx_create_uas( pjsip_module *tsx_user,
 
230
                                           pjsip_rx_data *rdata,
 
231
                                           pjsip_transaction **p_tsx );
 
232
 
 
233
 
 
234
/**
 
235
 * Lock/bind transaction to a specific transport/listener. This is optional,
 
236
 * as normally transport will be selected automatically based on the 
 
237
 * destination of the message upon resolver completion.
 
238
 *
 
239
 * @param tsx       The transaction.
 
240
 * @param sel       Transport selector containing the specification of
 
241
 *                  transport or listener to be used by this transaction
 
242
 *                  to send requests.
 
243
 *
 
244
 * @return          PJ_SUCCESS on success, or the appropriate error code.
 
245
 */
 
246
PJ_DECL(pj_status_t) pjsip_tsx_set_transport(pjsip_transaction *tsx,
 
247
                                             const pjsip_tpselector *sel);
 
248
 
 
249
/**
 
250
 * Call this function to manually feed a message to the transaction.
 
251
 * For UAS transaction, application MUST call this function after
 
252
 * UAS transaction has been created.
 
253
 *
 
254
 * This function SHOULD only be called to pass initial request message
 
255
 * to UAS transaction. Before this function returns, on_tsx_state()
 
256
 * callback of the transaction user will be called. If response message
 
257
 * is passed to this function, then on_rx_response() will also be called
 
258
 * before on_tsx_state().
 
259
 *
 
260
 * @param tsx       The transaction.
 
261
 * @param rdata     The message.
 
262
 */
 
263
PJ_DECL(void) pjsip_tsx_recv_msg( pjsip_transaction *tsx, 
 
264
                                  pjsip_rx_data *rdata);
 
265
 
 
266
/**
 
267
 * Transmit message in tdata with this transaction. It is possible to
 
268
 * pass NULL in tdata for UAC transaction, which in this case the last 
 
269
 * message transmitted, or the request message which was specified when
 
270
 * calling #pjsip_tsx_create_uac(), will be sent.
 
271
 *
 
272
 * This function decrements the reference counter of the transmit buffer
 
273
 * only when it returns PJ_SUCCESS;
 
274
 *
 
275
 * @param tsx       The transaction.
 
276
 * @param tdata     The outgoing message. If NULL is specified, then the
 
277
 *                  last message transmitted (or the message specified 
 
278
 *                  in UAC initialization) will be sent.
 
279
 *
 
280
 * @return          PJ_SUCCESS if successfull.
 
281
 */
 
282
PJ_DECL(pj_status_t) pjsip_tsx_send_msg( pjsip_transaction *tsx,
 
283
                                         pjsip_tx_data *tdata);
 
284
 
 
285
 
 
286
/**
 
287
 * Manually retransmit the last message transmitted by this transaction,
 
288
 * without updating the transaction state. This function is useful when
 
289
 * TU wants to maintain the retransmision by itself (for example,
 
290
 * retransmitting reliable provisional response).
 
291
 *
 
292
 * @param tsx       The transaction.
 
293
 * @param tdata     The outgoing message. If NULL is specified, then the
 
294
 *                  last message transmitted (or the message specified 
 
295
 *                  in UAC initialization) will be sent.
 
296
 *
 
297
 *
 
298
 * @return          PJ_SUCCESS if successful.
 
299
 */
 
300
PJ_DECL(pj_status_t) pjsip_tsx_retransmit_no_state(pjsip_transaction *tsx,
 
301
                                                   pjsip_tx_data *tdata);
 
302
 
 
303
 
 
304
/**
 
305
 * Create transaction key, which is used to match incoming requests 
 
306
 * or response (retransmissions) against transactions.
 
307
 *
 
308
 * @param pool      The pool
 
309
 * @param key       Output key.
 
310
 * @param role      The role of the transaction.
 
311
 * @param method    The method to be put as a key. 
 
312
 * @param rdata     The received data to calculate.
 
313
 *
 
314
 * @return          PJ_SUCCESS or the appropriate error code.
 
315
 */
 
316
PJ_DECL(pj_status_t) pjsip_tsx_create_key( pj_pool_t *pool,
 
317
                                           pj_str_t *key,
 
318
                                           pjsip_role_e role,
 
319
                                           const pjsip_method *method,
 
320
                                           const pjsip_rx_data *rdata );
 
321
 
 
322
/**
 
323
 * Force terminate transaction.
 
324
 *
 
325
 * @param tsx       The transaction.
 
326
 * @param code      The status code to report.
 
327
 */
 
328
PJ_DECL(pj_status_t) pjsip_tsx_terminate( pjsip_transaction *tsx,
 
329
                                          int code );
 
330
 
 
331
 
 
332
/**
 
333
 * Cease retransmission on the UAC transaction. The UAC transaction is
 
334
 * still considered running, and it will complete when either final
 
335
 * response is received or the transaction times out.
 
336
 *
 
337
 * This operation normally is used for INVITE transaction only, when
 
338
 * the transaction is cancelled before any provisional response has been
 
339
 * received.
 
340
 *
 
341
 * @param tsx       The transaction.
 
342
 *
 
343
 * @return          PJ_SUCCESS or the appropriate error code.
 
344
 */
 
345
PJ_DECL(pj_status_t) pjsip_tsx_stop_retransmit(pjsip_transaction *tsx);
 
346
 
 
347
 
 
348
/**
 
349
 * Start a timer to terminate transaction after the specified time
 
350
 * has elapsed. This function is only valid for INVITE transaction,
 
351
 * and only before final response is received for the INVITE transaction.
 
352
 * It is normally called after the UAC has sent CANCEL for this
 
353
 * INVITE transaction. 
 
354
 *
 
355
 * The purpose of this function is to terminate the transaction if UAS 
 
356
 * does not send final response to this INVITE transaction even after 
 
357
 * it sends 200/OK to CANCEL (for example when the UAS complies to RFC
 
358
 * 2543).
 
359
 *
 
360
 * Once this timer is set, the transaction will be terminated either when
 
361
 * a final response is received or the timer expires.
 
362
 *
 
363
 * @param tsx       The transaction.
 
364
 * @param millisec  Timeout value in milliseconds.
 
365
 *
 
366
 * @return          PJ_SUCCESS or the appropriate error code.
 
367
 */
 
368
PJ_DECL(pj_status_t) pjsip_tsx_set_timeout(pjsip_transaction *tsx,
 
369
                                           unsigned millisec);
 
370
 
 
371
 
 
372
/**
 
373
 * Get the transaction instance in the incoming message. If the message
 
374
 * has a corresponding transaction, this function will return non NULL
 
375
 * value.
 
376
 *
 
377
 * @param rdata     The incoming message buffer.
 
378
 *
 
379
 * @return          The transaction instance associated with this message,
 
380
 *                  or NULL if the message doesn't match any transactions.
 
381
 */
 
382
PJ_DECL(pjsip_transaction*) pjsip_rdata_get_tsx( pjsip_rx_data *rdata );
 
383
 
 
384
 
 
385
/**
 
386
 * @}
 
387
 */
 
388
 
 
389
/*
 
390
 * Internal.
 
391
 */
 
392
 
 
393
/*
 
394
 * Dump transaction layer.
 
395
 */
 
396
PJ_DECL(void) pjsip_tsx_layer_dump(pj_bool_t detail);
 
397
 
 
398
/**
 
399
 * Get the string name for the state.
 
400
 * @param state State
 
401
 */
 
402
PJ_DECL(const char *) pjsip_tsx_state_str(pjsip_tsx_state_e state);
 
403
 
 
404
/**
 
405
 * Get the role name.
 
406
 * @param role  Role.
 
407
 */
 
408
PJ_DECL(const char *) pjsip_role_name(pjsip_role_e role);
 
409
 
 
410
 
 
411
PJ_END_DECL
 
412
 
 
413
#endif  /* __PJSIP_TRANSACT_H__ */
 
414