← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjnath/include/pjnath/turn_session.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.0.1/pjnath/include/pjnath/turn_session.h
1
 
/* $Id: turn_session.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_SESSION_H__
21
 
#define __PJNATH_TURN_SESSION_H__
22
 
 
23
 
/**
24
 
 * @file turn_session.h
25
 
 * @brief Transport independent TURN client session.
26
 
 */
27
 
#include <pjnath/stun_session.h>
28
 
#include <pjlib-util/resolver.h>
29
 
 
30
 
 
31
 
PJ_BEGIN_DECL
32
 
 
33
 
 
34
 
/* **************************************************************************/
35
 
/**
36
 
@addtogroup PJNATH_TURN_SESSION
37
 
@{
38
 
 
39
 
The \ref PJNATH_TURN_SESSION is a transport-independent object to
40
 
manage a client TURN session. It contains the core logic for manage
41
 
the TURN client session as listed in \ref turn_op_sec, but
42
 
in transport-independent manner (i.e. it doesn't have a socket), so
43
 
that developer can integrate TURN client functionality into existing
44
 
framework that already has its own means to send and receive data,
45
 
or to support new transport types to TURN, such as TLS.
46
 
 
47
 
 
48
 
\section turn_sess_using_sec Using the TURN session
49
 
 
50
 
These steps describes how to use the TURN session:
51
 
 
52
 
 - <b>Creating the session</b>:\n
53
 
   use #pj_turn_session_create() to create the session.
54
 
 
55
 
 - <b>Configuring credential</b>:\n
56
 
   all TURN operations requires the use of authentication (it uses STUN
57
 
   long term autentication method). Use #pj_turn_session_set_credential()
58
 
   to configure the TURN credential to be used by the session.
59
 
 
60
 
 - <b>Configuring server</b>:\n
61
 
   application must call #pj_turn_session_set_server() before it can send
62
 
   Allocate request (with pj_turn_session_alloc()). This function will
63
 
   resolve the TURN server using DNS SRV resolution if the \a resolver
64
 
   is set. The server resolution process will complete asynchronously,
65
 
   and application will be notified in \a on_state() callback of the
66
 
   #pj_turn_session_cb structurewith the session state set to
67
 
   PJ_TURN_STATE_RESOLVED.
68
 
 
69
 
 - <b>Creating allocation</b>:\n
70
 
   create one "relay port" (or called <b>relayed-transport-address</b>
71
 
   in TURN terminology) in the TURN server by using #pj_turn_session_alloc().
72
 
   This will send Allocate request to the server. This function will complete
73
 
   immediately, and application will be notified about the allocation
74
 
   result in the \a on_state() callback of the #pj_turn_session_cb structure.
75
 
 
76
 
 - <b>Getting the allocation result</b>:\n
77
 
   if allocation is successful, the session state will progress to
78
 
   \a PJ_TURN_STATE_READY, otherwise the state will be
79
 
   \a PJ_TURN_STATE_DEALLOCATED or higher. Session state progression is
80
 
   reported in the \a on_state() callback of the #pj_turn_session_cb
81
 
   structure. On successful allocation, application may retrieve the
82
 
   allocation info by calling #pj_turn_session_get_info().
83
 
 
84
 
 - <b>Sending data through the relay</b>.\n
85
 
   Once allocation has been created, client may send data to any remote
86
 
   endpoints (called peers in TURN terminology) via the "relay port". It does
87
 
   so by calling #pj_turn_session_sendto(), giving the peer address
88
 
   in the function argument. But note that at this point peers are not allowed
89
 
   to send data towards the client (via the "relay port") before permission is
90
 
   installed for that peer.
91
 
 
92
 
 - <b>Creating permissions</b>.\n
93
 
   Permission needs to be created in the TURN server so that a peer can send
94
 
   data to the client via the relay port (a peer in this case is identified by
95
 
   its IP address). Without this, when the TURN server receives data from the
96
 
   peer in the "relay port", it will drop this data. Create the permission by
97
 
   calling #pj_turn_session_set_perm(), specifying the peer IP address in the
98
 
   argument (the port part of the address is ignored). More than one IP
99
 
   addresses may be specified.
100
 
 
101
 
 - <b>Receiving data from peers</b>.\n
102
 
   Once permission has been installed for the peer, any data received by the
103
 
   TURN server (from that peer) in the "relay port" will be relayed back to
104
 
   client by the server, and application will be notified via \a on_rx_data
105
 
   callback of the #pj_turn_session_cb.
106
 
 
107
 
 - <b>Using ChannelData</b>.\n
108
 
   TURN provides optimized framing to the data by using ChannelData
109
 
   packetization. The client activates this format for the specified peer by
110
 
   calling #pj_turn_session_bind_channel(). Data sent or received to/for
111
 
   this peer will then use ChannelData format instead of Send or Data
112
 
   Indications.
113
 
 
114
 
 - <b>Refreshing the allocation, permissions, and channel bindings</b>.\n
115
 
   Allocations, permissions, and channel bindings will be refreshed by the
116
 
   session automatically when they about to expire.
117
 
 
118
 
 - <b>Destroying the allocation</b>.\n
119
 
   Once the "relay port" is no longer needed, client destroys the allocation
120
 
   by calling #pj_turn_session_shutdown(). This function will return
121
 
   immediately, and application will be notified about the deallocation
122
 
   result in the \a on_state() callback of the #pj_turn_session_cb structure.
123
 
   Once the state has reached PJ_TURN_STATE_DESTROYING, application must
124
 
   assume that the session will be destroyed shortly after.
125
 
 
126
 
 */
127
 
 
128
 
/**
129
 
 * Opaque declaration for TURN client session.
130
 
 */
131
 
typedef struct pj_turn_session pj_turn_session;
132
 
 
133
 
 
134
 
/**
135
 
 * TURN transport types, which will be used both to specify the connection
136
 
 * type for reaching TURN server and the type of allocation transport to be
137
 
 * requested to server (the REQUESTED-TRANSPORT attribute).
138
 
 */
139
 
typedef enum pj_turn_tp_type
140
 
{
141
 
    /**
142
 
     * UDP transport, which value corresponds to IANA protocol number.
143
 
     */
144
 
    PJ_TURN_TP_UDP = 17,
145
 
 
146
 
    /**
147
 
     * TCP transport, which value corresponds to IANA protocol number.
148
 
     */
149
 
    PJ_TURN_TP_TCP = 6,
150
 
 
151
 
    /**
152
 
     * TLS transport. The TLS transport will only be used as the connection
153
 
     * type to reach the server and never as the allocation transport type.
154
 
     */
155
 
    PJ_TURN_TP_TLS = 255
156
 
 
157
 
} pj_turn_tp_type;
158
 
 
159
 
 
160
 
/** TURN session state */
161
 
typedef enum pj_turn_state_t
162
 
{
163
 
    /**
164
 
     * TURN session has just been created.
165
 
     */
166
 
    PJ_TURN_STATE_NULL,
167
 
 
168
 
    /**
169
 
     * TURN server has been configured and now is being resolved via
170
 
     * DNS SRV resolution.
171
 
     */
172
 
    PJ_TURN_STATE_RESOLVING,
173
 
 
174
 
    /**
175
 
     * TURN server has been resolved. If there is pending allocation to
176
 
     * be done, it will be invoked immediately.
177
 
     */
178
 
    PJ_TURN_STATE_RESOLVED,
179
 
 
180
 
    /**
181
 
     * TURN session has issued ALLOCATE request and is waiting for response
182
 
     * from the TURN server.
183
 
     */
184
 
    PJ_TURN_STATE_ALLOCATING,
185
 
 
186
 
    /**
187
 
     * TURN session has successfully allocated relay resoruce and now is
188
 
     * ready to be used.
189
 
     */
190
 
    PJ_TURN_STATE_READY,
191
 
 
192
 
    /**
193
 
     * TURN session has issued deallocate request and is waiting for a
194
 
     * response from the TURN server.
195
 
     */
196
 
    PJ_TURN_STATE_DEALLOCATING,
197
 
 
198
 
    /**
199
 
     * Deallocate response has been received. Normally the session will
200
 
     * proceed to DESTROYING state immediately.
201
 
     */
202
 
    PJ_TURN_STATE_DEALLOCATED,
203
 
 
204
 
    /**
205
 
     * TURN session is being destroyed.
206
 
     */
207
 
    PJ_TURN_STATE_DESTROYING
208
 
 
209
 
} pj_turn_state_t;
210
 
 
211
 
 
212
 
#pragma pack(1)
213
 
 
214
 
/**
215
 
 * This structure ChannelData header. All the fields are in network byte
216
 
 * order when it's on the wire.
217
 
 */
218
 
typedef struct pj_turn_channel_data
219
 
{
220
 
    pj_uint16_t ch_number;      /**< Channel number.    */
221
 
    pj_uint16_t length;         /**< Payload length.    */
222
 
} pj_turn_channel_data;
223
 
 
224
 
 
225
 
#pragma pack()
226
 
 
227
 
 
228
 
/**
229
 
 * Callback to receive events from TURN session.
230
 
 */
231
 
typedef struct pj_turn_session_cb
232
 
{
233
 
    /**
234
 
     * This callback will be called by the TURN session whenever it
235
 
     * needs to send outgoing message. Since the TURN session doesn't
236
 
     * have a socket on its own, this callback must be implemented.
237
 
     *
238
 
     * @param sess      The TURN session.
239
 
     * @param pkt       The packet/data to be sent.
240
 
     * @param pkt_len   Length of the packet/data.
241
 
     * @param dst_addr  Destination address of the packet.
242
 
     * @param addr_len  Length of the destination address.
243
 
     *
244
 
     * @return          The callback should return the status of the
245
 
     *                  send operation.
246
 
     */
247
 
    pj_status_t (*on_send_pkt)(pj_turn_session *sess,
248
 
                               const pj_uint8_t *pkt,
249
 
                               unsigned pkt_len,
250
 
                               const pj_sockaddr_t *dst_addr,
251
 
                               unsigned addr_len);
252
 
 
253
 
    /**
254
 
     * Notification when peer address has been bound successfully to
255
 
     * a channel number.
256
 
     *
257
 
     * This callback is optional since the nature of this callback is
258
 
     * for information only.
259
 
     *
260
 
     * @param sess      The TURN session.
261
 
     * @param peer_addr The peer address.
262
 
     * @param addr_len  Length of the peer address.
263
 
     * @param ch_num    The channel number associated with this peer address.
264
 
     */
265
 
    void (*on_channel_bound)(pj_turn_session *sess,
266
 
                             const pj_sockaddr_t *peer_addr,
267
 
                             unsigned addr_len,
268
 
                             unsigned ch_num);
269
 
 
270
 
    /**
271
 
     * Notification when incoming data has been received, either through
272
 
     * Data indication or ChannelData message from the TURN server.
273
 
     *
274
 
     * @param sess      The TURN session.
275
 
     * @param pkt       The data/payload of the Data Indication or ChannelData
276
 
     *                  packet.
277
 
     * @param pkt_len   Length of the data/payload.
278
 
     * @param peer_addr Peer address where this payload was received by
279
 
     *                  the TURN server.
280
 
     * @param addr_len  Length of the peer address.
281
 
     */
282
 
    void (*on_rx_data)(pj_turn_session *sess,
283
 
                       void *pkt,
284
 
                       unsigned pkt_len,
285
 
                       const pj_sockaddr_t *peer_addr,
286
 
                       unsigned addr_len);
287
 
 
288
 
    /**
289
 
     * Notification when TURN session state has changed. Application should
290
 
     * implement this callback at least to know that the TURN session is
291
 
     * going to be destroyed.
292
 
     *
293
 
     * @param sess      The TURN session.
294
 
     * @param old_state The previous state of the session.
295
 
     * @param new_state The current state of the session.
296
 
     */
297
 
    void (*on_state)(pj_turn_session *sess,
298
 
                     pj_turn_state_t old_state,
299
 
                     pj_turn_state_t new_state);
300
 
 
301
 
} pj_turn_session_cb;
302
 
 
303
 
 
304
 
/**
305
 
 * Allocation parameter, which can be given when application calls
306
 
 * pj_turn_session_alloc() to allocate relay address in the TURN server.
307
 
 * Application should call pj_turn_alloc_param_default() to initialize
308
 
 * this structure with the default values.
309
 
 */
310
 
typedef struct pj_turn_alloc_param
311
 
{
312
 
    /**
313
 
     * The requested BANDWIDTH. Default is zero to not request any
314
 
     * specific bandwidth. Note that this attribute has been deprecated
315
 
     * after TURN-08 draft, hence application should only use this
316
 
     * attribute when talking to TURN-07 or older version.
317
 
     */
318
 
    int     bandwidth;
319
 
 
320
 
    /**
321
 
     * The requested LIFETIME. Default is zero to not request any
322
 
     * explicit allocation lifetime.
323
 
     */
324
 
    int     lifetime;
325
 
 
326
 
    /**
327
 
     * If set to non-zero, the TURN session will periodically send blank
328
 
     * Send Indication every PJ_TURN_KEEP_ALIVE_SEC to refresh local
329
 
     * NAT bindings. Default is zero.
330
 
     */
331
 
    int     ka_interval;
332
 
 
333
 
} pj_turn_alloc_param;
334
 
 
335
 
 
336
 
/**
337
 
 * This structure describes TURN session info.
338
 
 */
339
 
typedef struct pj_turn_session_info
340
 
{
341
 
    /**
342
 
     * Session state.
343
 
     */
344
 
    pj_turn_state_t state;
345
 
 
346
 
    /**
347
 
     * Last error (if session was terminated because of error)
348
 
     */
349
 
    pj_status_t     last_status;
350
 
 
351
 
    /**
352
 
     * Type of connection to the TURN server.
353
 
     */
354
 
    pj_turn_tp_type conn_type;
355
 
 
356
 
    /**
357
 
     * The selected TURN server address.
358
 
     */
359
 
    pj_sockaddr     server;
360
 
 
361
 
    /**
362
 
     * Mapped address, as reported by the TURN server.
363
 
     */
364
 
    pj_sockaddr     mapped_addr;
365
 
 
366
 
    /**
367
 
     * The relay address
368
 
     */
369
 
    pj_sockaddr     relay_addr;
370
 
 
371
 
    /**
372
 
     * Current seconds before allocation expires.
373
 
     */
374
 
    int             lifetime;
375
 
 
376
 
} pj_turn_session_info;
377
 
 
378
 
 
379
 
/**
380
 
 * Initialize pj_turn_alloc_param with the default values.
381
 
 *
382
 
 * @param prm   The TURN allocation parameter to be initialized.
383
 
 */
384
 
PJ_DECL(void) pj_turn_alloc_param_default(pj_turn_alloc_param *prm);
385
 
 
386
 
 
387
 
/**
388
 
 * Duplicate pj_turn_alloc_param.
389
 
 *
390
 
 * @param pool  Pool to allocate memory (currently not used)
391
 
 * @param dst   Destination parameter.
392
 
 * @param src   Source parameter.
393
 
 */
394
 
PJ_DECL(void) pj_turn_alloc_param_copy(pj_pool_t *pool,
395
 
                                       pj_turn_alloc_param *dst,
396
 
                                       const pj_turn_alloc_param *src);
397
 
 
398
 
/**
399
 
 * Get string representation for the given TURN state.
400
 
 *
401
 
 * @param state The TURN session state.
402
 
 *
403
 
 * @return      The state name as NULL terminated string.
404
 
 */
405
 
PJ_DECL(const char*) pj_turn_state_name(pj_turn_state_t state);
406
 
 
407
 
 
408
 
/**
409
 
 * Create a TURN session instance with the specified address family and
410
 
 * connection type. Once TURN session instance is created, application
411
 
 * must call pj_turn_session_alloc() to allocate a relay address in the TURN
412
 
 * server.
413
 
 *
414
 
 * @param cfg           The STUN configuration which contains among other
415
 
 *                      things the ioqueue and timer heap instance for
416
 
 *                      the operation of this session.
417
 
 * @param name          Optional name to identify this session in the log.
418
 
 * @param af            Address family of the client connection. Currently
419
 
 *                      pj_AF_INET() and pj_AF_INET6() are supported.
420
 
 * @param conn_type     Connection type to the TURN server.
421
 
 * @param cb            Callback to receive events from the TURN session.
422
 
 * @param options       Option flags, currently this value must be zero.
423
 
 * @param user_data     Arbitrary application data to be associated with
424
 
 *                      this transport.
425
 
 * @param p_sess        Pointer to receive the created instance of the
426
 
 *                      TURN session.
427
 
 *
428
 
 * @return              PJ_SUCCESS if the operation has been successful,
429
 
 *                      or the appropriate error code on failure.
430
 
 */
431
 
PJ_DECL(pj_status_t) pj_turn_session_create(const pj_stun_config *cfg,
432
 
                                            const char *name,
433
 
                                            int af,
434
 
                                            pj_turn_tp_type conn_type,
435
 
                                            const pj_turn_session_cb *cb,
436
 
                                            unsigned options,
437
 
                                            void *user_data,
438
 
                                            pj_turn_session **p_sess);
439
 
 
440
 
/**
441
 
 * Shutdown TURN client session. This will gracefully deallocate and
442
 
 * destroy the client session.
443
 
 *
444
 
 * @param sess          The TURN client session.
445
 
 *
446
 
 * @return              PJ_SUCCESS if the operation has been successful,
447
 
 *                      or the appropriate error code on failure.
448
 
 */
449
 
PJ_DECL(pj_status_t) pj_turn_session_shutdown(pj_turn_session *sess);
450
 
 
451
 
 
452
 
/**
453
 
 * Forcefully destroy the TURN session. This will destroy the session
454
 
 * immediately. If there is an active allocation, the server will not
455
 
 * be notified about the client destruction.
456
 
 *
457
 
 * @param sess          The TURN client session.
458
 
 * @param last_err      Optional error code to be set to the session,
459
 
 *                      which would be returned back in the \a info
460
 
 *                      parameter of #pj_turn_session_get_info(). If
461
 
 *                      this argument value is PJ_SUCCESS, the error
462
 
 *                      code will not be set. If the session already
463
 
 *                      has an error code set, this function will not
464
 
 *                      overwrite that error code either.
465
 
 *
466
 
 * @return              PJ_SUCCESS if the operation has been successful,
467
 
 *                      or the appropriate error code on failure.
468
 
 */
469
 
PJ_DECL(pj_status_t) pj_turn_session_destroy(pj_turn_session *sess,
470
 
                                             pj_status_t last_err);
471
 
 
472
 
 
473
 
/**
474
 
 * Get the information about this TURN session and the allocation, if
475
 
 * any.
476
 
 *
477
 
 * @param sess          The TURN client session.
478
 
 * @param info          The structure to be initialized with the TURN
479
 
 *                      session info.
480
 
 *
481
 
 * @return              PJ_SUCCESS if the operation has been successful,
482
 
 *                      or the appropriate error code on failure.
483
 
 */
484
 
PJ_DECL(pj_status_t) pj_turn_session_get_info(pj_turn_session *sess,
485
 
                                              pj_turn_session_info *info);
486
 
 
487
 
/**
488
 
 * Associate a user data with this TURN session. The user data may then
489
 
 * be retrieved later with pj_turn_session_get_user_data().
490
 
 *
491
 
 * @param sess          The TURN client session.
492
 
 * @param user_data     Arbitrary data.
493
 
 *
494
 
 * @return              PJ_SUCCESS if the operation has been successful,
495
 
 *                      or the appropriate error code on failure.
496
 
 */
497
 
PJ_DECL(pj_status_t) pj_turn_session_set_user_data(pj_turn_session *sess,
498
 
                                                   void *user_data);
499
 
 
500
 
/**
501
 
 * Retrieve the previously assigned user data associated with this TURN
502
 
 * session.
503
 
 *
504
 
 * @param sess          The TURN client session.
505
 
 *
506
 
 * @return              The user/application data.
507
 
 */
508
 
PJ_DECL(void*) pj_turn_session_get_user_data(pj_turn_session *sess);
509
 
 
510
 
 
511
 
/**
512
 
 * Configure message logging. By default all flags are enabled.
513
 
 *
514
 
 * @param sess          The TURN client session.
515
 
 * @param flags         Bitmask combination of #pj_stun_sess_msg_log_flag
516
 
 */
517
 
PJ_DECL(void) pj_turn_session_set_log(pj_turn_session *sess,
518
 
                                      unsigned flags);
519
 
 
520
 
 
521
 
/**
522
 
 * Configure the SOFTWARE name to be sent in all STUN requests by the
523
 
 * TURN session.
524
 
 *
525
 
 * @param sess      The TURN client session.
526
 
 * @param sw        Software name string. If this argument is NULL or
527
 
 *                  empty, the session will not include SOFTWARE attribute
528
 
 *                  in STUN requests and responses.
529
 
 *
530
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
531
 
 */
532
 
PJ_DECL(pj_status_t) pj_turn_session_set_software_name(pj_turn_session *sess,
533
 
                                                       const pj_str_t *sw);
534
 
 
535
 
 
536
 
/**
537
 
 * Set the server or domain name of the server. Before the application
538
 
 * can send Allocate request (with pj_turn_session_alloc()), it must first
539
 
 * resolve the server address(es) using this function. This function will
540
 
 * resolve the TURN server using DNS SRV resolution if the \a resolver
541
 
 * is set. The server resolution process will complete asynchronously,
542
 
 * and application will be notified in \a on_state() callback with the
543
 
 * session state set to PJ_TURN_STATE_RESOLVED.
544
 
 *
545
 
 * Application may call with pj_turn_session_alloc() before the server
546
 
 * resolution completes. In this case, the operation will be queued by
547
 
 * the session, and it will be sent once the server resolution completes.
548
 
 *
549
 
 * @param sess          The TURN client session.
550
 
 * @param domain        The domain, hostname, or IP address of the TURN
551
 
 *                      server. When this parameter contains domain name,
552
 
 *                      the \a resolver parameter must be set to activate
553
 
 *                      DNS SRV resolution.
554
 
 * @param default_port  The default TURN port number to use when DNS SRV
555
 
 *                      resolution is not used. If DNS SRV resolution is
556
 
 *                      used, the server port number will be set from the
557
 
 *                      DNS SRV records.
558
 
 * @param resolver      If this parameter is not NULL, then the \a domain
559
 
 *                      parameter will be first resolved with DNS SRV and
560
 
 *                      then fallback to using DNS A/AAAA resolution when
561
 
 *                      DNS SRV resolution fails. If this parameter is
562
 
 *                      NULL, the \a domain parameter will be resolved as
563
 
 *                      hostname.
564
 
 *
565
 
 * @return              PJ_SUCCESS if the operation has been successfully
566
 
 *                      queued, or the appropriate error code on failure.
567
 
 *                      When this function returns PJ_SUCCESS, the final
568
 
 *                      result of the resolution process will be notified
569
 
 *                      to application in \a on_state() callback.
570
 
 */
571
 
PJ_DECL(pj_status_t) pj_turn_session_set_server(pj_turn_session *sess,
572
 
                                                const pj_str_t *domain,
573
 
                                                int default_port,
574
 
                                                pj_dns_resolver *resolver);
575
 
 
576
 
 
577
 
/**
578
 
 * Set credential to be used to authenticate against TURN server.
579
 
 * Application must call this function before sending Allocate request
580
 
 * with pj_turn_session_alloc().
581
 
 *
582
 
 * @param sess          The TURN client session
583
 
 * @param cred          STUN credential to be used.
584
 
 *
585
 
 * @return              PJ_SUCCESS if the operation has been successful,
586
 
 *                      or the appropriate error code on failure.
587
 
 */
588
 
PJ_DECL(pj_status_t) pj_turn_session_set_credential(pj_turn_session *sess,
589
 
                                              const pj_stun_auth_cred *cred);
590
 
 
591
 
 
592
 
/**
593
 
 * Allocate a relay address/resource in the TURN server by sending TURN
594
 
 * Allocate request. Application must first initiate the server resolution
595
 
 * process with pj_turn_session_set_server() and set the credential to be
596
 
 * used with pj_turn_session_set_credential() before calling this function.
597
 
 *
598
 
 * This function will complete asynchronously, and the application will be
599
 
 * notified about the allocation result in \a on_state() callback. The
600
 
 * TURN session state will move to PJ_TURN_STATE_READY if allocation is
601
 
 * successful, and PJ_TURN_STATE_DEALLOCATING or greater state if allocation
602
 
 * has failed.
603
 
 *
604
 
 * Once allocation has been successful, the TURN session will keep this
605
 
 * allocation alive until the session is destroyed, by sending periodic
606
 
 * allocation refresh to the TURN server.
607
 
 *
608
 
 * @param sess          The TURN client session.
609
 
 * @param param         Optional TURN allocation parameter.
610
 
 *
611
 
 * @return              PJ_SUCCESS if the operation has been successfully
612
 
 *                      initiated or the appropriate error code on failure.
613
 
 */
614
 
PJ_DECL(pj_status_t) pj_turn_session_alloc(pj_turn_session *sess,
615
 
                                           const pj_turn_alloc_param *param);
616
 
 
617
 
 
618
 
/**
619
 
 * Create or renew permission in the TURN server for the specified peer IP
620
 
 * addresses. Application must install permission for a particular (peer)
621
 
 * IP address before it sends any data to that IP address, or otherwise
622
 
 * the TURN server will drop the data.
623
 
 *
624
 
 * @param sess          The TURN client session.
625
 
 * @param addr_cnt      Number of IP addresses.
626
 
 * @param addr          Array of peer IP addresses. Only the address family
627
 
 *                      and IP address portion of the socket address matter.
628
 
 * @param options       Specify 1 to let the TURN client session automatically
629
 
 *                      renew the permission later when they are about to
630
 
 *                      expire.
631
 
 *
632
 
 * @return              PJ_SUCCESS if the operation has been successfully
633
 
 *                      issued, or the appropriate error code. Note that
634
 
 *                      the operation itself will complete asynchronously.
635
 
 */
636
 
PJ_DECL(pj_status_t) pj_turn_session_set_perm(pj_turn_session *sess,
637
 
                                              unsigned addr_cnt,
638
 
                                              const pj_sockaddr addr[],
639
 
                                              unsigned options);
640
 
 
641
 
 
642
 
/**
643
 
 * Send a data to the specified peer address via the TURN relay. This
644
 
 * function will encapsulate the data as STUN Send Indication or TURN
645
 
 * ChannelData packet and send the message to the TURN server. The TURN
646
 
 * server then will send the data to the peer.
647
 
 *
648
 
 * The allocation (pj_turn_session_alloc()) must have been successfully
649
 
 * created before application can relay any data.
650
 
 *
651
 
 * Since TURN session is transport independent, this function will
652
 
 * ultimately call \a on_send_pkt() callback to request the application
653
 
 * to actually send the packet containing the data to the TURN server.
654
 
 *
655
 
 * @param sess          The TURN client session.
656
 
 * @param pkt           The data/packet to be sent to peer.
657
 
 * @param pkt_len       Length of the data.
658
 
 * @param peer_addr     The remote peer address (the ultimate destination
659
 
 *                      of the data, and not the TURN server address).
660
 
 * @param addr_len      Length of the address.
661
 
 *
662
 
 * @return              PJ_SUCCESS if the operation has been successful,
663
 
 *                      or the appropriate error code on failure.
664
 
 */
665
 
PJ_DECL(pj_status_t) pj_turn_session_sendto(pj_turn_session *sess,
666
 
                                            const pj_uint8_t *pkt,
667
 
                                            unsigned pkt_len,
668
 
                                            const pj_sockaddr_t *peer_addr,
669
 
                                            unsigned addr_len);
670
 
 
671
 
/**
672
 
 * Optionally establish channel binding for the specified a peer address.
673
 
 * This function will assign a unique channel number for the peer address
674
 
 * and request channel binding to the TURN server for this address. When
675
 
 * a channel has been bound to a peer, the TURN client and TURN server
676
 
 * will exchange data using ChannelData encapsulation format, which has
677
 
 * lower bandwidth overhead than Send Indication (the default format used
678
 
 * when peer address is not bound to a channel).
679
 
 *
680
 
 * This function will complete asynchronously, and application will be
681
 
 * notified about the result in \a on_channel_bound() callback.
682
 
 *
683
 
 * @param sess          The TURN client session.
684
 
 * @param peer          The remote peer address.
685
 
 * @param addr_len      Length of the address.
686
 
 *
687
 
 * @return              PJ_SUCCESS if the operation has been successfully
688
 
 *                      initiated, or the appropriate error code on failure.
689
 
 */
690
 
PJ_DECL(pj_status_t) pj_turn_session_bind_channel(pj_turn_session *sess,
691
 
                                                  const pj_sockaddr_t *peer,
692
 
                                                  unsigned addr_len);
693
 
 
694
 
/**
695
 
 * Notify TURN client session upon receiving a packet from server. Since
696
 
 * the TURN session is transport independent, it does not read packet from
697
 
 * any sockets, and rather relies on application giving it packets that
698
 
 * are received from the TURN server. The session then processes this packet
699
 
 * and decides whether it is part of TURN protocol exchange or if it is a
700
 
 * data to be reported back to user, which in this case it will call the
701
 
 * \a on_rx_data() callback.
702
 
 *
703
 
 * @param sess          The TURN client session.
704
 
 * @param pkt           The packet as received from the TURN server. This
705
 
 *                      should contain either STUN encapsulated message or
706
 
 *                      a ChannelData packet.
707
 
 * @param pkt_len       The length of the packet.
708
 
 * @param parsed_len    Optional argument to receive the number of parsed
709
 
 *                      or processed data from the packet.
710
 
 *
711
 
 * @return              The function may return non-PJ_SUCCESS if it receives
712
 
 *                      non-STUN and non-ChannelData packet, or if the
713
 
 *                      \a on_rx_data() returns non-PJ_SUCCESS;
714
 
 */
715
 
PJ_DECL(pj_status_t) pj_turn_session_on_rx_pkt(pj_turn_session *sess,
716
 
                                               void *pkt,
717
 
                                               pj_size_t pkt_len,
718
 
                                               pj_size_t *parsed_len);
719
 
 
720
 
 
721
 
/**
722
 
 * @}
723
 
 */
724
 
 
725
 
 
726
 
PJ_END_DECL
727
 
 
728
 
 
729
 
#endif  /* __PJNATH_TURN_SESSION_H__ */