← Back to branch summary

~noskcaj/ubuntu/saucy/sflphone/merge-1.2.3-2

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject/pjnath/include/pjnath/turn_sock.h

  • Committer: Jackson Doak
  • Date: 2013-07-10 21:04:46 UTC
  • mfrom: (20.1.3 sid)
  • Revision ID: noskcaj@ubuntu.com-20130710210446-y8f587vza807icr9
https://launchpad.net/bugs/1196978
Properly merged from upstream.

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject/pjnath/include/pjnath/turn_sock.h
1
 
/* $Id: turn_sock.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_TURN_SOCK_H__
21
 
#define __PJNATH_TURN_SOCK_H__
22
 
 
23
 
/**
24
 
 * @file turn_sock.h
25
 
 * @brief TURN relay using UDP client as transport protocol
26
 
 */
27
 
#include <pjnath/turn_session.h>
28
 
#include <pj/sock_qos.h>
29
 
 
30
 
 
31
 
PJ_BEGIN_DECL
32
 
 
33
 
 
34
 
/* **************************************************************************/
35
 
/**
36
 
@addtogroup PJNATH_TURN_SOCK
37
 
@{
38
 
 
39
 
This is a ready to use object for relaying application data via a TURN server,
40
 
by managing all the operations in \ref turn_op_sec.
41
 
 
42
 
\section turnsock_using_sec Using TURN transport
43
 
 
44
 
This object provides a thin wrapper to the \ref PJNATH_TURN_SESSION, hence the
45
 
API is very much the same (apart from the obvious difference in the names).
46
 
Please see \ref PJNATH_TURN_SESSION for the documentation on how to use the
47
 
session.
48
 
 
49
 
\section turnsock_samples_sec Samples
50
 
 
51
 
The \ref turn_client_sample is a sample application to use the
52
 
\ref PJNATH_TURN_SOCK.
53
 
 
54
 
Also see <b>\ref samples_page</b> for other samples.
55
 
 
56
 
 */
57
 
 
58
 
 
59
 
/** 
60
 
 * Opaque declaration for TURN client.
61
 
 */
62
 
typedef struct pj_turn_sock pj_turn_sock;
63
 
 
64
 
/**
65
 
 * This structure contains callbacks that will be called by the TURN
66
 
 * transport.
67
 
 */
68
 
typedef struct pj_turn_sock_cb
69
 
{
70
 
    /**
71
 
     * Notification when incoming data has been received from the remote
72
 
     * peer via the TURN server. The data reported in this callback will
73
 
     * be the exact data as sent by the peer (e.g. the TURN encapsulation
74
 
     * such as Data Indication or ChannelData will be removed before this
75
 
     * function is called).
76
 
     *
77
 
     * @param turn_sock     The TURN client transport.
78
 
     * @param data          The data as received from the peer.    
79
 
     * @param data_len      Length of the data.
80
 
     * @param peer_addr     The peer address.
81
 
     * @param addr_len      The length of the peer address.
82
 
     */
83
 
    void (*on_rx_data)(pj_turn_sock *turn_sock,
84
 
                       void *pkt,
85
 
                       unsigned pkt_len,
86
 
                       const pj_sockaddr_t *peer_addr,
87
 
                       unsigned addr_len);
88
 
 
89
 
    /**
90
 
     * Notification when TURN session state has changed. Application should
91
 
     * implement this callback to monitor the progress of the TURN session.
92
 
     *
93
 
     * @param turn_sock     The TURN client transport.
94
 
     * @param old_state     Previous state.
95
 
     * @param new_state     Current state.
96
 
     */
97
 
    void (*on_state)(pj_turn_sock *turn_sock, 
98
 
                     pj_turn_state_t old_state,
99
 
                     pj_turn_state_t new_state);
100
 
 
101
 
} pj_turn_sock_cb;
102
 
 
103
 
 
104
 
/**
105
 
 * This structure describes options that can be specified when creating
106
 
 * the TURN socket. Application should call #pj_turn_sock_cfg_default()
107
 
 * to initialize this structure with its default values before using it.
108
 
 */
109
 
typedef struct pj_turn_sock_cfg
110
 
{
111
 
    /**
112
 
     * QoS traffic type to be set on this transport. When application wants
113
 
     * to apply QoS tagging to the transport, it's preferable to set this
114
 
     * field rather than \a qos_param fields since this is more portable.
115
 
     *
116
 
     * Default value is PJ_QOS_TYPE_BEST_EFFORT.
117
 
     */
118
 
    pj_qos_type qos_type;
119
 
 
120
 
    /**
121
 
     * Set the low level QoS parameters to the transport. This is a lower
122
 
     * level operation than setting the \a qos_type field and may not be
123
 
     * supported on all platforms.
124
 
     *
125
 
     * By default all settings in this structure are not set.
126
 
     */
127
 
    pj_qos_params qos_params;
128
 
 
129
 
    /**
130
 
     * Specify if STUN socket should ignore any errors when setting the QoS
131
 
     * traffic type/parameters.
132
 
     *
133
 
     * Default: PJ_TRUE
134
 
     */
135
 
    pj_bool_t qos_ignore_error;
136
 
 
137
 
} pj_turn_sock_cfg;
138
 
 
139
 
 
140
 
/**
141
 
 * Initialize pj_turn_sock_cfg structure with default values.
142
 
 */
143
 
PJ_DECL(void) pj_turn_sock_cfg_default(pj_turn_sock_cfg *cfg);
144
 
 
145
 
 
146
 
/**
147
 
 * Create a TURN transport instance with the specified address family and
148
 
 * connection type. Once TURN transport instance is created, application
149
 
 * must call pj_turn_sock_alloc() to allocate a relay address in the TURN
150
 
 * server.
151
 
 *
152
 
 * @param cfg           The STUN configuration which contains among other
153
 
 *                      things the ioqueue and timer heap instance for
154
 
 *                      the operation of this transport.
155
 
 * @param af            Address family of the client connection. Currently
156
 
 *                      pj_AF_INET() and pj_AF_INET6() are supported.
157
 
 * @param conn_type     Connection type to the TURN server. Both TCP and
158
 
 *                      UDP are supported.
159
 
 * @param cb            Callback to receive events from the TURN transport.
160
 
 * @param setting       Optional settings to be specified to the transport.
161
 
 *                      If this parameter is NULL, default values will be
162
 
 *                      used.
163
 
 * @param user_data     Arbitrary application data to be associated with
164
 
 *                      this transport.
165
 
 * @param p_turn_sock   Pointer to receive the created instance of the
166
 
 *                      TURN transport.
167
 
 *
168
 
 * @return              PJ_SUCCESS if the operation has been successful,
169
 
 *                      or the appropriate error code on failure.
170
 
 */
171
 
PJ_DECL(pj_status_t) pj_turn_sock_create(pj_stun_config *cfg,
172
 
                                         int af,
173
 
                                         pj_turn_tp_type conn_type,
174
 
                                         const pj_turn_sock_cb *cb,
175
 
                                         const pj_turn_sock_cfg *setting,
176
 
                                         void *user_data,
177
 
                                         pj_turn_sock **p_turn_sock);
178
 
 
179
 
/**
180
 
 * Destroy the TURN transport instance. This will gracefully close the
181
 
 * connection between the client and the TURN server. Although this
182
 
 * function will return immediately, the TURN socket deletion may continue
183
 
 * in the background and the application may still get state changes
184
 
 * notifications from this transport.
185
 
 *
186
 
 * @param turn_sock     The TURN transport instance.
187
 
 */
188
 
PJ_DECL(void) pj_turn_sock_destroy(pj_turn_sock *turn_sock);
189
 
 
190
 
 
191
 
/**
192
 
 * Associate a user data with this TURN transport. The user data may then
193
 
 * be retrieved later with #pj_turn_sock_get_user_data().
194
 
 *
195
 
 * @param turn_sock     The TURN transport instance.
196
 
 * @param user_data     Arbitrary data.
197
 
 *
198
 
 * @return              PJ_SUCCESS if the operation has been successful,
199
 
 *                      or the appropriate error code on failure.
200
 
 */
201
 
PJ_DECL(pj_status_t) pj_turn_sock_set_user_data(pj_turn_sock *turn_sock,
202
 
                                                void *user_data);
203
 
 
204
 
/**
205
 
 * Retrieve the previously assigned user data associated with this TURN
206
 
 * transport.
207
 
 *
208
 
 * @param turn_sock     The TURN transport instance.
209
 
 *
210
 
 * @return              The user/application data.
211
 
 */
212
 
PJ_DECL(void*) pj_turn_sock_get_user_data(pj_turn_sock *turn_sock);
213
 
 
214
 
 
215
 
/**
216
 
 * Get the TURN transport info. The transport info contains, among other
217
 
 * things, the allocated relay address.
218
 
 *
219
 
 * @param turn_sock     The TURN transport instance.
220
 
 * @param info          Pointer to be filled with TURN transport info.
221
 
 *
222
 
 * @return              PJ_SUCCESS if the operation has been successful,
223
 
 *                      or the appropriate error code on failure.
224
 
 */
225
 
PJ_DECL(pj_status_t) pj_turn_sock_get_info(pj_turn_sock *turn_sock,
226
 
                                           pj_turn_session_info *info);
227
 
 
228
 
/**
229
 
 * Acquire the internal mutex of the TURN transport. Application may need
230
 
 * to call this function to synchronize access to other objects alongside 
231
 
 * the TURN transport, to avoid deadlock.
232
 
 *
233
 
 * @param turn_sock     The TURN transport instance.
234
 
 *
235
 
 * @return              PJ_SUCCESS if the operation has been successful,
236
 
 *                      or the appropriate error code on failure.
237
 
 */
238
 
PJ_DECL(pj_status_t) pj_turn_sock_lock(pj_turn_sock *turn_sock);
239
 
 
240
 
 
241
 
/**
242
 
 * Release the internal mutex previously held with pj_turn_sock_lock().
243
 
 *
244
 
 * @param turn_sock     The TURN transport instance.
245
 
 *
246
 
 * @return              PJ_SUCCESS if the operation has been successful,
247
 
 *                      or the appropriate error code on failure.
248
 
 */
249
 
PJ_DECL(pj_status_t) pj_turn_sock_unlock(pj_turn_sock *turn_sock);
250
 
 
251
 
 
252
 
/**
253
 
 * Set STUN message logging for this TURN session. 
254
 
 * See #pj_stun_session_set_log().
255
 
 *
256
 
 * @param turn_sock     The TURN transport instance.
257
 
 * @param flags         Bitmask combination of #pj_stun_sess_msg_log_flag
258
 
 */
259
 
PJ_DECL(void) pj_turn_sock_set_log(pj_turn_sock *turn_sock,
260
 
                                   unsigned flags);
261
 
 
262
 
/**
263
 
 * Configure the SOFTWARE name to be sent in all STUN requests by the
264
 
 * TURN session.
265
 
 *
266
 
 * @param turn_sock     The TURN transport instance.
267
 
 * @param sw        Software name string. If this argument is NULL or
268
 
 *                  empty, the session will not include SOFTWARE attribute
269
 
 *                  in STUN requests and responses.
270
 
 *
271
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
272
 
 */
273
 
PJ_DECL(pj_status_t) pj_turn_sock_set_software_name(pj_turn_sock *turn_sock,
274
 
                                                    const pj_str_t *sw);
275
 
 
276
 
 
277
 
/**
278
 
 * Allocate a relay address/resource in the TURN server. This function
279
 
 * will resolve the TURN server using DNS SRV (if desired) and send TURN
280
 
 * \a Allocate request using the specified credential to allocate a relay
281
 
 * address in the server. This function completes asynchronously, and
282
 
 * application will be notified when the allocation process has been
283
 
 * successful in the \a on_state() callback when the state is set to
284
 
 * PJ_TURN_STATE_READY. If the allocation fails, the state will be set
285
 
 * to PJ_TURN_STATE_DEALLOCATING or greater.
286
 
 *
287
 
 * @param turn_sock     The TURN transport instance.
288
 
 * @param domain        The domain, hostname, or IP address of the TURN
289
 
 *                      server. When this parameter contains domain name,
290
 
 *                      the \a resolver parameter must be set to activate
291
 
 *                      DNS SRV resolution.
292
 
 * @param default_port  The default TURN port number to use when DNS SRV
293
 
 *                      resolution is not used. If DNS SRV resolution is
294
 
 *                      used, the server port number will be set from the
295
 
 *                      DNS SRV records.
296
 
 * @param resolver      If this parameter is not NULL, then the \a domain
297
 
 *                      parameter will be first resolved with DNS SRV and
298
 
 *                      then fallback to using DNS A/AAAA resolution when
299
 
 *                      DNS SRV resolution fails. If this parameter is
300
 
 *                      NULL, the \a domain parameter will be resolved as
301
 
 *                      hostname.
302
 
 * @param cred          The STUN credential to be used for the TURN server.
303
 
 * @param param         Optional TURN allocation parameter.
304
 
 *
305
 
 * @return              PJ_SUCCESS if the operation has been successfully
306
 
 *                      queued, or the appropriate error code on failure.
307
 
 *                      When this function returns PJ_SUCCESS, the final
308
 
 *                      result of the allocation process will be notified
309
 
 *                      to application in \a on_state() callback.
310
 
 *                      
311
 
 */
312
 
PJ_DECL(pj_status_t) pj_turn_sock_alloc(pj_turn_sock *turn_sock,
313
 
                                        const pj_str_t *domain,
314
 
                                        int default_port,
315
 
                                        pj_dns_resolver *resolver,
316
 
                                        const pj_stun_auth_cred *cred,
317
 
                                        const pj_turn_alloc_param *param);
318
 
 
319
 
/**
320
 
 * Create or renew permission in the TURN server for the specified peer IP
321
 
 * addresses. Application must install permission for a particular (peer)
322
 
 * IP address before it sends any data to that IP address, or otherwise
323
 
 * the TURN server will drop the data.
324
 
 *
325
 
 * @param turn_sock     The TURN transport instance.
326
 
 * @param addr_cnt      Number of IP addresses.
327
 
 * @param addr          Array of peer IP addresses. Only the address family
328
 
 *                      and IP address portion of the socket address matter.
329
 
 * @param options       Specify 1 to let the TURN client session automatically
330
 
 *                      renew the permission later when they are about to
331
 
 *                      expire.
332
 
 *
333
 
 * @return              PJ_SUCCESS if the operation has been successfully
334
 
 *                      issued, or the appropriate error code. Note that
335
 
 *                      the operation itself will complete asynchronously.
336
 
 */
337
 
PJ_DECL(pj_status_t) pj_turn_sock_set_perm(pj_turn_sock *turn_sock,
338
 
                                           unsigned addr_cnt,
339
 
                                           const pj_sockaddr addr[],
340
 
                                           unsigned options);
341
 
 
342
 
/**
343
 
 * Send a data to the specified peer address via the TURN relay. This 
344
 
 * function will encapsulate the data as STUN Send Indication or TURN
345
 
 * ChannelData packet and send the message to the TURN server. The TURN
346
 
 * server then will send the data to the peer.
347
 
 *
348
 
 * The allocation (pj_turn_sock_alloc()) must have been successfully
349
 
 * created before application can relay any data.
350
 
 *
351
 
 * @param turn_sock     The TURN transport instance.
352
 
 * @param pkt           The data/packet to be sent to peer.
353
 
 * @param pkt_len       Length of the data.
354
 
 * @param peer_addr     The remote peer address (the ultimate destination
355
 
 *                      of the data, and not the TURN server address).
356
 
 * @param addr_len      Length of the address.
357
 
 *
358
 
 * @return              PJ_SUCCESS if the operation has been successful,
359
 
 *                      or the appropriate error code on failure.
360
 
 */ 
361
 
PJ_DECL(pj_status_t) pj_turn_sock_sendto(pj_turn_sock *turn_sock,
362
 
                                        const pj_uint8_t *pkt,
363
 
                                        unsigned pkt_len,
364
 
                                        const pj_sockaddr_t *peer_addr,
365
 
                                        unsigned addr_len);
366
 
 
367
 
/**
368
 
 * Optionally establish channel binding for the specified a peer address.
369
 
 * This function will assign a unique channel number for the peer address
370
 
 * and request channel binding to the TURN server for this address. When
371
 
 * a channel has been bound to a peer, the TURN transport and TURN server
372
 
 * will exchange data using ChannelData encapsulation format, which has
373
 
 * lower bandwidth overhead than Send Indication (the default format used
374
 
 * when peer address is not bound to a channel).
375
 
 *
376
 
 * @param turn_sock     The TURN transport instance.
377
 
 * @param peer          The remote peer address.
378
 
 * @param addr_len      Length of the address.
379
 
 *
380
 
 * @return              PJ_SUCCESS if the operation has been successful,
381
 
 *                      or the appropriate error code on failure.
382
 
 */
383
 
PJ_DECL(pj_status_t) pj_turn_sock_bind_channel(pj_turn_sock *turn_sock,
384
 
                                               const pj_sockaddr_t *peer,
385
 
                                               unsigned addr_len);
386
 
 
387
 
 
388
 
/**
389
 
 * @}
390
 
 */
391
 
 
392
 
 
393
 
PJ_END_DECL
394
 
 
395
 
 
396
 
#endif  /* __PJNATH_TURN_SOCK_H__ */
397