← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjnath/include/pjnath/stun_transaction.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
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/pjnath/include/pjnath/stun_transaction.h
 
1
/* $Id: stun_transaction.h 4360 2013-02-21 11:26:35Z 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 __PJNATH_STUN_TRANSACTION_H__
 
21
#define __PJNATH_STUN_TRANSACTION_H__
 
22
 
 
23
/**
 
24
 * @file stun_transaction.h
 
25
 * @brief STUN transaction
 
26
 */
 
27
 
 
28
#include <pjnath/stun_msg.h>
 
29
#include <pjnath/stun_config.h>
 
30
#include <pj/lock.h>
 
31
 
 
32
 
 
33
PJ_BEGIN_DECL
 
34
 
 
35
 
 
36
/* **************************************************************************/
 
37
/**
 
38
 * @defgroup PJNATH_STUN_TRANSACTION STUN Client Transaction
 
39
 * @brief STUN client transaction
 
40
 * @ingroup PJNATH_STUN_BASE
 
41
 * @{
 
42
 *
 
43
 The @ref PJNATH_STUN_TRANSACTION is used to manage outgoing STUN request,
 
44
 for example to retransmit the request and to notify application about the
 
45
 completion of the request.
 
46
 
 
47
 The @ref PJNATH_STUN_TRANSACTION does not use any networking operations,
 
48
 but instead application must supply the transaction with a callback to
 
49
 be used by the transaction to send outgoing requests. This way the STUN
 
50
 transaction is made more generic and can work with different types of
 
51
 networking codes in application.
 
52
 
 
53
 
 
54
 */
 
55
 
 
56
/**
 
57
 * Opaque declaration of STUN client transaction.
 
58
 */
 
59
typedef struct pj_stun_client_tsx pj_stun_client_tsx;
 
60
 
 
61
/**
 
62
 * STUN client transaction callback.
 
63
 */
 
64
typedef struct pj_stun_tsx_cb
 
65
{
 
66
    /**
 
67
     * This callback is called when the STUN transaction completed.
 
68
     *
 
69
     * @param tsx           The STUN transaction.
 
70
     * @param status        Status of the transaction. Status PJ_SUCCESS
 
71
     *                      means that the request has received a successful
 
72
     *                      response.
 
73
     * @param response      The STUN response, which value may be NULL if
 
74
     *                      \a status is not PJ_SUCCESS.
 
75
     * @param src_addr      The source address of the response, if response 
 
76
     *                      is not NULL.
 
77
     * @param src_addr_len  The length of the source address.
 
78
     */
 
79
    void        (*on_complete)(pj_stun_client_tsx *tsx,
 
80
                               pj_status_t status, 
 
81
                               const pj_stun_msg *response,
 
82
                               const pj_sockaddr_t *src_addr,
 
83
                               unsigned src_addr_len);
 
84
 
 
85
    /**
 
86
     * This callback is called by the STUN transaction when it wants to send
 
87
     * outgoing message.
 
88
     *
 
89
     * @param tsx           The STUN transaction instance.
 
90
     * @param stun_pkt      The STUN packet to be sent.
 
91
     * @param pkt_size      Size of the STUN packet.
 
92
     *
 
93
     * @return              If return value of the callback is not PJ_SUCCESS,
 
94
     *                      the transaction will fail. Application MUST return
 
95
     *                      PJNATH_ESTUNDESTROYED if it has destroyed the
 
96
     *                      transaction in this callback.
 
97
     */
 
98
    pj_status_t (*on_send_msg)(pj_stun_client_tsx *tsx,
 
99
                               const void *stun_pkt,
 
100
                               pj_size_t pkt_size);
 
101
 
 
102
    /**
 
103
     * This callback is called after the timer that was scheduled by
 
104
     * #pj_stun_client_tsx_schedule_destroy() has elapsed. Application
 
105
     * should call #pj_stun_client_tsx_destroy() upon receiving this
 
106
     * callback.
 
107
     *
 
108
     * This callback is optional if application will not call 
 
109
     * #pj_stun_client_tsx_schedule_destroy().
 
110
     *
 
111
     * @param tsx           The STUN transaction instance.
 
112
     */
 
113
    void (*on_destroy)(pj_stun_client_tsx *tsx);
 
114
 
 
115
} pj_stun_tsx_cb;
 
116
 
 
117
 
 
118
 
 
119
/**
 
120
 * Create an instance of STUN client transaction. The STUN client 
 
121
 * transaction is used to transmit outgoing STUN request and to 
 
122
 * ensure the reliability of the request by periodically retransmitting
 
123
 * the request, if necessary.
 
124
 *
 
125
 * @param cfg           The STUN endpoint, which will be used to retrieve
 
126
 *                      various settings for the transaction.
 
127
 * @param pool          Pool to be used to allocate memory from.
 
128
 * @param grp_lock      Group lock to synchronize.
 
129
 * @param cb            Callback structure, to be used by the transaction
 
130
 *                      to send message and to notify the application about
 
131
 *                      the completion of the transaction.
 
132
 * @param p_tsx         Pointer to receive the transaction instance.
 
133
 *
 
134
 * @return              PJ_SUCCESS on success, or the appropriate error code.
 
135
 */
 
136
PJ_DECL(pj_status_t) pj_stun_client_tsx_create( pj_stun_config *cfg,
 
137
                                                pj_pool_t *pool,
 
138
                                                pj_grp_lock_t *grp_lock,
 
139
                                                const pj_stun_tsx_cb *cb,
 
140
                                                pj_stun_client_tsx **p_tsx);
 
141
 
 
142
/**
 
143
 * Schedule timer to destroy the transaction after the transaction is 
 
144
 * complete. Application normally calls this function in the on_complete()
 
145
 * callback. When this timer elapsed, the on_destroy() callback will be 
 
146
 * called.
 
147
 *
 
148
 * This is convenient to let the STUN transaction absorbs any response 
 
149
 * for the previous request retransmissions. If application doesn't want
 
150
 * this, it can destroy the transaction immediately by calling 
 
151
 * #pj_stun_client_tsx_destroy().
 
152
 *
 
153
 * @param tsx           The STUN transaction.
 
154
 * @param delay         The delay interval before on_destroy() callback
 
155
 *                      is called.
 
156
 *
 
157
 * @return              PJ_SUCCESS on success, or the appropriate error code.
 
158
 */
 
159
PJ_DECL(pj_status_t) 
 
160
pj_stun_client_tsx_schedule_destroy(pj_stun_client_tsx *tsx,
 
161
                                    const pj_time_val *delay);
 
162
 
 
163
 
 
164
/**
 
165
 * Stop the client transaction.
 
166
 *
 
167
 * @param tsx           The STUN transaction.
 
168
 *
 
169
 * @return              PJ_SUCCESS on success or PJ_EINVAL if the parameter
 
170
 *                      is NULL.
 
171
 */
 
172
PJ_DECL(pj_status_t) pj_stun_client_tsx_stop(pj_stun_client_tsx *tsx);
 
173
 
 
174
 
 
175
/**
 
176
 * Check if transaction has completed.
 
177
 *
 
178
 * @param tsx           The STUN transaction.
 
179
 *
 
180
 * @return              Non-zero if transaction has completed.
 
181
 */
 
182
PJ_DECL(pj_bool_t) pj_stun_client_tsx_is_complete(pj_stun_client_tsx *tsx);
 
183
 
 
184
 
 
185
/**
 
186
 * Associate an arbitrary data with the STUN transaction. This data
 
187
 * can be then retrieved later from the transaction, by using
 
188
 * pj_stun_client_tsx_get_data() function.
 
189
 *
 
190
 * @param tsx           The STUN client transaction.
 
191
 * @param data          Application data to be associated with the
 
192
 *                      STUN transaction.
 
193
 *
 
194
 * @return              PJ_SUCCESS on success.
 
195
 */
 
196
PJ_DECL(pj_status_t) pj_stun_client_tsx_set_data(pj_stun_client_tsx *tsx,
 
197
                                                 void *data);
 
198
 
 
199
 
 
200
/**
 
201
 * Get the user data that was previously associated with the STUN 
 
202
 * transaction.
 
203
 *
 
204
 * @param tsx           The STUN client transaction.
 
205
 *
 
206
 * @return              The user data.
 
207
 */
 
208
PJ_DECL(void*) pj_stun_client_tsx_get_data(pj_stun_client_tsx *tsx);
 
209
 
 
210
 
 
211
/**
 
212
 * Start the STUN client transaction by sending STUN request using
 
213
 * this transaction. If reliable transport such as TCP or TLS is used,
 
214
 * the retransmit flag should be set to PJ_FALSE because reliablity
 
215
 * will be assured by the transport layer.
 
216
 *
 
217
 * @param tsx           The STUN client transaction.
 
218
 * @param retransmit    Should this message be retransmitted by the
 
219
 *                      STUN transaction.
 
220
 * @param pkt           The STUN packet to send.
 
221
 * @param pkt_len       Length of STUN packet.
 
222
 *
 
223
 * @return              PJ_SUCCESS on success, or PJNATH_ESTUNDESTROYED 
 
224
 *                      when the user has destroyed the transaction in 
 
225
 *                      \a on_send_msg() callback, or any other error code
 
226
 *                      as returned by \a on_send_msg() callback.
 
227
 */
 
228
PJ_DECL(pj_status_t) pj_stun_client_tsx_send_msg(pj_stun_client_tsx *tsx,
 
229
                                                 pj_bool_t retransmit,
 
230
                                                 void *pkt,
 
231
                                                 unsigned pkt_len);
 
232
 
 
233
/**
 
234
 * Request to retransmit the request. Normally application should not need
 
235
 * to call this function since retransmission would be handled internally,
 
236
 * but this functionality is needed by ICE.
 
237
 *
 
238
 * @param tsx           The STUN client transaction instance.
 
239
 * @param mod_count     Boolean flag to indicate whether transmission count
 
240
 *                      needs to be incremented.
 
241
 *
 
242
 * @return              PJ_SUCCESS on success, or PJNATH_ESTUNDESTROYED 
 
243
 *                      when the user has destroyed the transaction in 
 
244
 *                      \a on_send_msg() callback, or any other error code
 
245
 *                      as returned by \a on_send_msg() callback.
 
246
 */
 
247
PJ_DECL(pj_status_t) pj_stun_client_tsx_retransmit(pj_stun_client_tsx *tsx,
 
248
                                                   pj_bool_t mod_count);
 
249
 
 
250
 
 
251
/**
 
252
 * Notify the STUN transaction about the arrival of STUN response.
 
253
 * If the STUN response contains a final error (300 and greater), the
 
254
 * transaction will be terminated and callback will be called. If the
 
255
 * STUN response contains response code 100-299, retransmission
 
256
 * will  cease, but application must still call this function again
 
257
 * with a final response later to allow the transaction to complete.
 
258
 *
 
259
 * @param tsx           The STUN client transaction instance.
 
260
 * @param msg           The incoming STUN message.
 
261
 * @param src_addr      The source address of the packet.
 
262
 * @param src_addr_len  The length of the source address.
 
263
 *
 
264
 * @return              PJ_SUCCESS on success or the appropriate error code.
 
265
 */
 
266
PJ_DECL(pj_status_t) pj_stun_client_tsx_on_rx_msg(pj_stun_client_tsx *tsx,
 
267
                                                  const pj_stun_msg *msg,
 
268
                                                  const pj_sockaddr_t*src_addr,
 
269
                                                  unsigned src_addr_len);
 
270
 
 
271
 
 
272
/**
 
273
 * @}
 
274
 */
 
275
 
 
276
 
 
277
PJ_END_DECL
 
278
 
 
279
 
 
280
#endif  /* __PJNATH_STUN_TRANSACTION_H__ */
 
281