Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjnath / src / pjturn-srv / turn.h
1 /* $Id$ */
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 __PJ_TURN_SRV_TURN_H__
21 #define __PJ_TURN_SRV_TURN_H__
22
23 #include <pjlib.h>
24 #include <pjnath.h>
25
26 typedef struct pj_turn_relay_res    pj_turn_relay_res;
27 typedef struct pj_turn_listener     pj_turn_listener;
28 typedef struct pj_turn_transport    pj_turn_transport;
29 typedef struct pj_turn_permission   pj_turn_permission;
30 typedef struct pj_turn_allocation   pj_turn_allocation;
31 typedef struct pj_turn_srv          pj_turn_srv;
32 typedef struct pj_turn_pkt          pj_turn_pkt;
33
34
35 #define PJ_TURN_INVALID_LIS_ID      ((unsigned)-1)
36
37 /** 
38  * Get transport type name string.
39  */
40 PJ_DECL(const char*) pj_turn_tp_type_name(int tp_type);
41
42 /**
43  * This structure describes TURN relay resource. An allocation allocates
44  * one relay resource, and optionally it may reserve another resource.
45  */
46 struct pj_turn_relay_res
47 {
48     /** Hash table key */
49     struct {
50         /** Transport type. */
51         int                 tp_type;
52
53         /** Transport/relay address */
54         pj_sockaddr         addr;
55     } hkey;
56
57     /** Allocation who requested or reserved this resource. */
58     pj_turn_allocation *allocation;
59
60     /** Username used in credential */
61     pj_str_t        user;
62
63     /** Realm used in credential. */
64     pj_str_t        realm;
65
66     /** Lifetime, in seconds. */
67     unsigned        lifetime;
68
69     /** Relay/allocation expiration time */
70     pj_time_val     expiry;
71
72     /** Timeout timer entry */
73     pj_timer_entry  timer;
74
75     /** Transport. */
76     struct {
77         /** Transport/relay socket */
78         pj_sock_t           sock;
79
80         /** Transport/relay ioqueue */
81         pj_ioqueue_key_t    *key;
82
83         /** Read operation key. */
84         pj_ioqueue_op_key_t read_key;
85
86         /** The incoming packet buffer */
87         char                rx_pkt[PJ_TURN_MAX_PKT_LEN];
88
89         /** Source address of the packet. */
90         pj_sockaddr         src_addr;
91
92         /** Source address length */
93         int                 src_addr_len;
94
95         /** The outgoing packet buffer. This must be 3wbit aligned. */
96         char                tx_pkt[PJ_TURN_MAX_PKT_LEN+4];
97     } tp;
98 };
99
100
101 /****************************************************************************/
102 /*
103  * TURN Allocation API
104  */
105
106 /**
107  * This structure describes key to lookup TURN allocations in the
108  * allocation hash table.
109  */
110 typedef struct pj_turn_allocation_key
111 {
112     int             tp_type;    /**< Transport type.        */
113     pj_sockaddr     clt_addr;   /**< Client's address.      */
114 } pj_turn_allocation_key;
115
116
117 /**
118  * This structure describes TURN pj_turn_allocation session.
119  */
120 struct pj_turn_allocation
121 {
122     /** Hash table key to identify client. */
123     pj_turn_allocation_key hkey;
124
125     /** Pool for this allocation. */
126     pj_pool_t           *pool;
127
128     /** Object name for logging identification */
129     char                *obj_name;
130
131     /** Client info (IP address and port) */
132     char                info[80];
133
134     /** Mutex */
135     pj_lock_t           *lock;
136
137     /** Server instance. */
138     pj_turn_srv         *server;
139
140     /** Transport to send/receive packets to/from client. */
141     pj_turn_transport   *transport;
142
143     /** The relay resource for this allocation. */
144     pj_turn_relay_res   relay;
145
146     /** Relay resource reserved by this allocation, if any */
147     pj_turn_relay_res   *resv;
148
149     /** Requested bandwidth */
150     unsigned            bandwidth;
151
152     /** STUN session for this client */
153     pj_stun_session     *sess;
154
155     /** Credential for this STUN session. */
156     pj_stun_auth_cred    cred;
157
158     /** Peer hash table (keyed by peer address) */
159     pj_hash_table_t     *peer_table;
160
161     /** Channel hash table (keyed by channel number) */
162     pj_hash_table_t     *ch_table;
163 };
164
165
166 /**
167  * This structure describes the hash table key to lookup TURN
168  * permission.
169  */
170 typedef struct pj_turn_permission_key
171 {
172     /** Peer address. */
173     pj_sockaddr         peer_addr;
174
175 } pj_turn_permission_key;
176
177
178 /**
179  * This structure describes TURN pj_turn_permission or channel.
180  */
181 struct pj_turn_permission
182 {
183     /** Hash table key */
184     pj_turn_permission_key hkey;
185
186     /** TURN allocation that owns this permission/channel */
187     pj_turn_allocation  *allocation;
188
189     /** Optional channel number, or PJ_TURN_INVALID_CHANNEL if channel number
190      *  is not requested for this permission. 
191      */
192     pj_uint16_t         channel;
193
194     /** Permission expiration time. */
195     pj_time_val         expiry;
196 };
197
198 /**
199  * Create new allocation.
200  */
201 PJ_DECL(pj_status_t) pj_turn_allocation_create(pj_turn_transport *transport,
202                                                const pj_sockaddr_t *src_addr,
203                                                unsigned src_addr_len,
204                                                const pj_stun_rx_data *rdata,
205                                                pj_stun_session *srv_sess,
206                                                pj_turn_allocation **p_alloc);
207 /**
208  * Destroy allocation.
209  */
210 PJ_DECL(void) pj_turn_allocation_destroy(pj_turn_allocation *alloc);
211
212
213 /**
214  * Handle incoming packet from client.
215  */
216 PJ_DECL(void) pj_turn_allocation_on_rx_client_pkt(pj_turn_allocation *alloc,
217                                                   pj_turn_pkt *pkt);
218
219 /**
220  * Handle transport closure.
221  */
222 PJ_DECL(void) pj_turn_allocation_on_transport_closed(pj_turn_allocation *alloc,
223                                                      pj_turn_transport *tp);
224
225 /****************************************************************************/
226 /*
227  * TURN Listener API
228  */
229
230 /**
231  * This structure describes TURN listener socket. A TURN listener socket
232  * listens for incoming connections from clients.
233  */
234 struct pj_turn_listener
235 {
236     /** Object name/identification */
237     char                *obj_name;
238
239     /** Slightly longer info about this listener */
240     char                info[80];
241
242     /** TURN server instance. */
243     pj_turn_srv         *server;
244
245     /** Listener index in the server */
246     unsigned            id;
247
248     /** Pool for this listener. */
249     pj_pool_t          *pool;
250
251     /** Transport type. */
252     int                 tp_type;
253
254     /** Bound address of this listener. */
255     pj_sockaddr         addr;
256
257     /** Socket. */
258     pj_sock_t           sock;
259
260     /** Flags. */
261     unsigned            flags;
262
263     /** Destroy handler */
264     pj_status_t         (*destroy)(pj_turn_listener*);
265 };
266
267
268 /**
269  * This structure describes TURN transport socket which is used to send and
270  * receive packets towards client.
271  */
272 struct pj_turn_transport
273 {
274     /** Object name/identification */
275     char                *obj_name;
276
277     /** Slightly longer info about this listener */
278     char                *info;
279
280     /** Listener instance */
281     pj_turn_listener    *listener;
282
283     /** Sendto handler */
284     pj_status_t         (*sendto)(pj_turn_transport *tp,
285                                   const void *packet,
286                                   pj_size_t size,
287                                   unsigned flag,
288                                   const pj_sockaddr_t *addr,
289                                   int addr_len);
290
291     /** Addref handler */
292     void                (*add_ref)(pj_turn_transport *tp,
293                                    pj_turn_allocation *alloc);
294
295     /** Decref handler */
296     void                (*dec_ref)(pj_turn_transport *tp,
297                                    pj_turn_allocation *alloc);
298
299 };
300
301
302 /**
303  * An incoming packet.
304  */
305 struct pj_turn_pkt
306 {
307     /** Pool for this packet */
308     pj_pool_t               *pool;
309
310     /** Transport where the packet was received. */
311     pj_turn_transport       *transport;
312
313     /** Packet buffer (must be 32bit aligned). */
314     pj_uint8_t              pkt[PJ_TURN_MAX_PKT_LEN];
315
316     /** Size of the packet */
317     pj_size_t               len;
318
319     /** Arrival time. */
320     pj_time_val             rx_time;
321
322     /** Source transport type and source address. */
323     pj_turn_allocation_key   src;
324
325     /** Source address length. */
326     int                     src_addr_len;
327 };
328
329
330 /**
331  * Create a UDP listener on the specified port.
332  */
333 PJ_DECL(pj_status_t) pj_turn_listener_create_udp(pj_turn_srv *srv,
334                                                  int af,
335                                                  const pj_str_t *bound_addr,
336                                                  unsigned port,
337                                                  unsigned concurrency_cnt,
338                                                  unsigned flags,
339                                                  pj_turn_listener **p_lis);
340
341 /**
342  * Create a TCP listener on the specified port.
343  */
344 PJ_DECL(pj_status_t) pj_turn_listener_create_tcp(pj_turn_srv *srv,
345                                                  int af,
346                                                  const pj_str_t *bound_addr,
347                                                  unsigned port,
348                                                  unsigned concurrency_cnt,
349                                                  unsigned flags,
350                                                  pj_turn_listener **p_lis);
351
352 /**
353  * Destroy listener.
354  */
355 PJ_DECL(pj_status_t) pj_turn_listener_destroy(pj_turn_listener *listener);
356
357
358 /**
359  * Add a reference to a transport.
360  */
361 PJ_DECL(void) pj_turn_transport_add_ref(pj_turn_transport *transport,
362                                         pj_turn_allocation *alloc);
363
364
365 /**
366  * Decrement transport reference counter.
367  */
368 PJ_DECL(void) pj_turn_transport_dec_ref(pj_turn_transport *transport,
369                                         pj_turn_allocation *alloc);
370
371
372
373 /****************************************************************************/
374 /*
375  * TURN Server API
376  */
377 /**
378  * This structure describes TURN pj_turn_srv instance.
379  */
380 struct pj_turn_srv
381 {
382     /** Object name */
383     char        *obj_name;
384
385     /** Core settings */
386     struct {
387         /** Pool factory */
388         pj_pool_factory *pf;
389
390         /** Pool for this server instance. */
391         pj_pool_t       *pool;
392
393         /** Global Ioqueue */
394         pj_ioqueue_t    *ioqueue;
395
396         /** Mutex */
397         pj_lock_t       *lock;
398
399         /** Global timer heap instance. */
400         pj_timer_heap_t *timer_heap;
401
402         /** Number of listeners */
403         unsigned         lis_cnt;
404
405         /** Array of listeners. */
406         pj_turn_listener **listener;
407
408         /** STUN session to handle initial Allocate request. */
409         pj_stun_session *stun_sess;
410
411         /** Number of worker threads. */
412         unsigned        thread_cnt;
413
414         /** Array of worker threads. */
415         pj_thread_t     **thread;
416
417         /** Thread quit signal */
418         pj_bool_t       quit;
419
420         /** STUN config. */
421         pj_stun_config   stun_cfg;
422
423         /** STUN auth credential. */
424         pj_stun_auth_cred cred;
425
426         /** Thread local ID for storing credential */
427         long             tls_key, tls_data;
428
429     } core;
430
431     
432     /** Hash tables */
433     struct {
434         /** Allocations hash table, indexed by transport type and
435          *  client address. 
436          */
437         pj_hash_table_t *alloc;
438
439         /** Relay resource hash table, indexed by transport type and
440          *  relay address. 
441          */
442         pj_hash_table_t *res;
443
444     } tables;
445
446     /** Ports settings */
447     struct {
448         /** Minimum UDP port number. */
449         pj_uint16_t         min_udp;
450
451         /** Maximum UDP port number. */
452         pj_uint16_t         max_udp;
453
454         /** Next UDP port number. */
455         pj_uint16_t         next_udp;
456
457
458         /** Minimum TCP port number. */
459         pj_uint16_t         min_tcp;
460
461         /** Maximum TCP port number. */
462         pj_uint16_t         max_tcp;
463
464         /** Next TCP port number. */
465         pj_uint16_t         next_tcp;
466
467     } ports;
468 };
469
470
471 /** 
472  * Create server.
473  */
474 PJ_DECL(pj_status_t) pj_turn_srv_create(pj_pool_factory *pf,
475                                         pj_turn_srv **p_srv);
476
477 /** 
478  * Destroy server.
479  */
480 PJ_DECL(pj_status_t) pj_turn_srv_destroy(pj_turn_srv *srv);
481
482 /** 
483  * Add listener.
484  */
485 PJ_DECL(pj_status_t) pj_turn_srv_add_listener(pj_turn_srv *srv,
486                                               pj_turn_listener *lis);
487
488 /**
489  * Register an allocation.
490  */
491 PJ_DECL(pj_status_t) pj_turn_srv_register_allocation(pj_turn_srv *srv,
492                                                      pj_turn_allocation *alloc);
493
494 /**
495  * Unregister an allocation.
496  */
497 PJ_DECL(pj_status_t) pj_turn_srv_unregister_allocation(pj_turn_srv *srv,
498                                                        pj_turn_allocation *alloc);
499
500 /**
501  * This callback is called by UDP listener on incoming packet.
502  */
503 PJ_DECL(void) pj_turn_srv_on_rx_pkt(pj_turn_srv *srv, 
504                                     pj_turn_pkt *pkt);
505
506
507 #endif  /* __PJ_TURN_SRV_TURN_H__ */
508