← Back to branch summary

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

« back to all changes in this revision

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