Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjnath / include / pjnath / stun_sock.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 __PJNATH_STUN_SOCK_H__
21 #define __PJNATH_STUN_SOCK_H__
22
23 /**
24  * @file stun_sock.h
25  * @brief STUN aware socket transport
26  */
27 #include <pjnath/stun_config.h>
28 #include <pjlib-util/resolver.h>
29 #include <pj/ioqueue.h>
30 #include <pj/sock.h>
31 #include <pj/sock_qos.h>
32
33
34 PJ_BEGIN_DECL
35
36
37 /**
38  * @addtogroup PJNATH_STUN_SOCK
39  * @{
40  *
41  * The STUN transport provides asynchronous UDP like socket transport
42  * with the additional STUN capability. It has the following features:
43  *
44  *  - API to send and receive UDP packets
45  *
46  *  - multiplex STUN and non-STUN incoming packets and distinguish between
47  *    STUN responses that belong to internal requests with application data
48  *    (the application data may be STUN packets as well)
49  *
50  *  - DNS SRV resolution to the STUN server (if wanted), along with fallback
51  *    to DNS A resolution if SRV record is not found.
52  *
53  *  - STUN keep-alive maintenance, and handle changes to the mapped address
54  *    (when the NAT binding changes)
55  *
56  */
57
58 /**
59  * Opaque type to represent a STUN transport.
60  */
61 typedef struct pj_stun_sock pj_stun_sock;
62
63 /**
64  * Types of operation being reported in \a on_status() callback of
65  * pj_stun_sock_cb. Application may retrieve the string representation
66  * of these constants with pj_stun_sock_op_name().
67  */
68 typedef enum pj_stun_sock_op
69 {
70     /**
71      * Asynchronous DNS resolution.
72      */
73     PJ_STUN_SOCK_DNS_OP         = 1,
74
75     /**
76      * Initial STUN Binding request.
77      */
78     PJ_STUN_SOCK_BINDING_OP,
79
80     /**
81      * Subsequent STUN Binding request for keeping the binding
82      * alive.
83      */
84     PJ_STUN_SOCK_KEEP_ALIVE_OP,
85
86     /**
87      * IP address change notification from the keep-alive operation.
88      */
89     PJ_STUN_SOCK_MAPPED_ADDR_CHANGE
90
91
92 } pj_stun_sock_op;
93
94
95 /**
96  * This structure contains callbacks that will be called by the STUN
97  * transport to notify application about various events.
98  */
99 typedef struct pj_stun_sock_cb
100 {
101     /**
102      * Notification when incoming packet has been received.
103      *
104      * @param stun_sock The STUN transport.
105      * @param data      The packet.
106      * @param data_len  Length of the packet.
107      * @param src_addr  The source address of the packet.
108      * @param addr_len  The length of the source address.
109      *
110      * @return          Application should normally return PJ_TRUE to let
111      *                  the STUN transport continue its operation. However
112      *                  it must return PJ_FALSE if it has destroyed the
113      *                  STUN transport in this callback.
114      */
115     pj_bool_t (*on_rx_data)(pj_stun_sock *stun_sock,
116                             void *pkt,
117                             unsigned pkt_len,
118                             const pj_sockaddr_t *src_addr,
119                             unsigned addr_len);
120
121     /**
122      * Notifification when asynchronous send operation has completed.
123      *
124      * @param stun_sock The STUN transport.
125      * @param send_key  The send operation key that was given in
126      *                  #pj_stun_sock_sendto().
127      * @param sent      If value is positive non-zero it indicates the
128      *                  number of data sent. When the value is negative,
129      *                  it contains the error code which can be retrieved
130      *                  by negating the value (i.e. status=-sent).
131      *
132      * @return          Application should normally return PJ_TRUE to let
133      *                  the STUN transport continue its operation. However
134      *                  it must return PJ_FALSE if it has destroyed the
135      *                  STUN transport in this callback.
136      */
137     pj_bool_t (*on_data_sent)(pj_stun_sock *stun_sock,
138                               pj_ioqueue_op_key_t *send_key,
139                               pj_ssize_t sent);
140
141     /**
142      * Notification when the status of the STUN transport has changed. This
143      * callback may be called for the following conditions:
144      *  - the first time the publicly mapped address has been resolved from
145      *    the STUN server, this callback will be called with \a op argument
146      *    set to PJ_STUN_SOCK_BINDING_OP \a status  argument set to 
147      *    PJ_SUCCESS.
148      *  - anytime when the transport has detected that the publicly mapped
149      *    address has changed, this callback will be called with \a op
150      *    argument set to PJ_STUN_SOCK_KEEP_ALIVE_OP and \a status
151      *    argument set to PJ_SUCCESS. On this case and the case above,
152      *    application will get the resolved public address in the
153      *    #pj_stun_sock_info structure.
154      *  - for any terminal error (such as STUN time-out, DNS resolution
155      *    failure, or keep-alive failure), this callback will be called 
156      *    with the \a status argument set to non-PJ_SUCCESS.
157      *
158      * @param stun_sock The STUN transport.
159      * @param op        The operation that triggers the callback.
160      * @param status    The status.
161      *
162      * @return          Must return PJ_FALSE if it has destroyed the
163      *                  STUN transport in this callback. Application should
164      *                  normally destroy the socket and return PJ_FALSE
165      *                  upon encountering terminal error, otherwise it
166      *                  should return PJ_TRUE to let the STUN socket operation
167      *                  continues.
168      */
169     pj_bool_t   (*on_status)(pj_stun_sock *stun_sock, 
170                              pj_stun_sock_op op,
171                              pj_status_t status);
172
173 } pj_stun_sock_cb;
174
175
176 /**
177  * This structure contains information about the STUN transport. Application
178  * may query this information by calling #pj_stun_sock_get_info().
179  */
180 typedef struct pj_stun_sock_info
181 {
182     /**
183      * The bound address of the socket.
184      */
185     pj_sockaddr     bound_addr;
186
187     /**
188      * IP address of the STUN server.
189      */
190     pj_sockaddr     srv_addr;
191
192     /**
193      * The publicly mapped address. It may contain zero address when the
194      * mapped address has not been resolved. Application may query whether
195      * this field contains valid address with pj_sockaddr_has_addr().
196      */
197     pj_sockaddr     mapped_addr;
198
199     /**
200      * Number of interface address aliases. The interface address aliases
201      * are list of all interface addresses in this host.
202      */
203     unsigned        alias_cnt;
204
205     /**
206      * Array of interface address aliases.
207      */
208     pj_sockaddr     aliases[PJ_ICE_ST_MAX_CAND];
209
210 } pj_stun_sock_info;
211
212
213 /**
214  * This describe the settings to be given to the STUN transport during its
215  * creation. Application should initialize this structure by calling
216  * #pj_stun_sock_cfg_default().
217  */
218 typedef struct pj_stun_sock_cfg
219 {
220     /**
221      * Packet buffer size. Default value is PJ_STUN_SOCK_PKT_LEN.
222      */
223     unsigned max_pkt_size;
224
225     /**
226      * Specify the number of simultaneous asynchronous read operations to
227      * be invoked to the ioqueue. Having more than one read operations will
228      * increase performance on multiprocessor systems since the application
229      * will be able to process more than one incoming packets simultaneously.
230      * Default value is 1.
231      */
232     unsigned async_cnt;
233
234     /**
235      * Specify the interface where the socket should be bound to. If the
236      * address is zero, socket will be bound to INADDR_ANY. If the address
237      * is non-zero, socket will be bound to this address only, and the
238      * transport will have only one address alias (the \a alias_cnt field
239      * in #pj_stun_sock_info structure.
240      */
241     pj_sockaddr bound_addr;
242
243     /**
244      * Specify the STUN keep-alive duration, in seconds. The STUN transport
245      * does keep-alive by sending STUN Binding request to the STUN server. 
246      * If this value is zero, the PJ_STUN_KEEP_ALIVE_SEC value will be used.
247      * If the value is negative, it will disable STUN keep-alive.
248      */
249     int ka_interval;
250
251     /**
252      * QoS traffic type to be set on this transport. When application wants
253      * to apply QoS tagging to the transport, it's preferable to set this
254      * field rather than \a qos_param fields since this is more portable.
255      *
256      * Default value is PJ_QOS_TYPE_BEST_EFFORT.
257      */
258     pj_qos_type qos_type;
259
260     /**
261      * Set the low level QoS parameters to the transport. This is a lower
262      * level operation than setting the \a qos_type field and may not be
263      * supported on all platforms.
264      *
265      * By default all settings in this structure are disabled.
266      */
267     pj_qos_params qos_params;
268
269     /**
270      * Specify if STUN socket should ignore any errors when setting the QoS
271      * traffic type/parameters.
272      *
273      * Default: PJ_TRUE
274      */
275     pj_bool_t qos_ignore_error;
276
277 } pj_stun_sock_cfg;
278
279
280
281 /**
282  * Retrieve the name representing the specified operation.
283  */
284 PJ_DECL(const char*) pj_stun_sock_op_name(pj_stun_sock_op op);
285
286
287 /**
288  * Initialize the STUN transport setting with its default values.
289  *
290  * @param cfg   The STUN transport config.
291  */
292 PJ_DECL(void) pj_stun_sock_cfg_default(pj_stun_sock_cfg *cfg);
293
294
295 /**
296  * Create the STUN transport using the specified configuration. Once
297  * the STUN transport has been create, application should call
298  * #pj_stun_sock_start() to start the transport.
299  *
300  * @param stun_cfg      The STUN configuration which contains among other
301  *                      things the ioqueue and timer heap instance for
302  *                      the operation of this transport.
303  * @param af            Address family of socket. Currently pj_AF_INET()
304  *                      and pj_AF_INET6() are supported. 
305  * @param name          Optional name to be given to this transport to
306  *                      assist debugging.
307  * @param cb            Callback to receive events/data from the transport.
308  * @param cfg           Optional transport settings.
309  * @param user_data     Arbitrary application data to be associated with
310  *                      this transport.
311  * @param p_sock        Pointer to receive the created transport instance.
312  *
313  * @return              PJ_SUCCESS if the operation has been successful,
314  *                      or the appropriate error code on failure.
315  */
316 PJ_DECL(pj_status_t) pj_stun_sock_create(pj_stun_config *stun_cfg,
317                                          const char *name,
318                                          int af,
319                                          const pj_stun_sock_cb *cb,
320                                          const pj_stun_sock_cfg *cfg,
321                                          void *user_data,
322                                          pj_stun_sock **p_sock);
323
324
325 /**
326  * Start the STUN transport. This will start the DNS SRV resolution for
327  * the STUN server (if desired), and once the server is resolved, STUN
328  * Binding request will be sent to resolve the publicly mapped address.
329  * Once the initial STUN Binding response is received, the keep-alive
330  * timer will be started.
331  *
332  * @param stun_sock     The STUN transport instance.
333  * @param domain        The domain, hostname, or IP address of the TURN
334  *                      server. When this parameter contains domain name,
335  *                      the \a resolver parameter must be set to activate
336  *                      DNS SRV resolution.
337  * @param default_port  The default STUN port number to use when DNS SRV
338  *                      resolution is not used. If DNS SRV resolution is
339  *                      used, the server port number will be set from the
340  *                      DNS SRV records. The recommended value for this
341  *                      parameter is PJ_STUN_PORT.
342  * @param resolver      If this parameter is not NULL, then the \a domain
343  *                      parameter will be first resolved with DNS SRV and
344  *                      then fallback to using DNS A/AAAA resolution when
345  *                      DNS SRV resolution fails. If this parameter is
346  *                      NULL, the \a domain parameter will be resolved as
347  *                      hostname.
348  *
349  * @return              PJ_SUCCESS if the operation has been successfully
350  *                      queued, or the appropriate error code on failure.
351  *                      When this function returns PJ_SUCCESS, the final
352  *                      result of the allocation process will be notified
353  *                      to application in \a on_state() callback.
354  */
355 PJ_DECL(pj_status_t) pj_stun_sock_start(pj_stun_sock *stun_sock,
356                                         const pj_str_t *domain,
357                                         pj_uint16_t default_port,
358                                         pj_dns_resolver *resolver);
359
360 /**
361  * Destroy the STUN transport.
362  *
363  * @param sock          The STUN transport socket.
364  *
365  * @return              PJ_SUCCESS if the operation has been successful,
366  *                      or the appropriate error code on failure.
367  */
368 PJ_DECL(pj_status_t) pj_stun_sock_destroy(pj_stun_sock *sock);
369
370
371 /**
372  * Associate a user data with this STUN transport. The user data may then
373  * be retrieved later with #pj_stun_sock_get_user_data().
374  *
375  * @param stun_sock     The STUN transport instance.
376  * @param user_data     Arbitrary data.
377  *
378  * @return              PJ_SUCCESS if the operation has been successful,
379  *                      or the appropriate error code on failure.
380  */
381 PJ_DECL(pj_status_t) pj_stun_sock_set_user_data(pj_stun_sock *stun_sock,
382                                                 void *user_data);
383
384 /**
385  * Retrieve the previously assigned user data associated with this STUN
386  * transport.
387  *
388  * @param stun_sock     The STUN transport instance.
389  *
390  * @return              The user/application data.
391  */
392 PJ_DECL(void*) pj_stun_sock_get_user_data(pj_stun_sock *stun_sock);
393
394
395 /**
396  * Get the STUN transport info. The transport info contains, among other
397  * things, the allocated relay address.
398  *
399  * @param stun_sock     The STUN transport instance.
400  * @param info          Pointer to be filled with STUN transport info.
401  *
402  * @return              PJ_SUCCESS if the operation has been successful,
403  *                      or the appropriate error code on failure.
404  */
405 PJ_DECL(pj_status_t) pj_stun_sock_get_info(pj_stun_sock *stun_sock,
406                                            pj_stun_sock_info *info);
407
408
409 /**
410  * Send a data to the specified address. This function may complete
411  * asynchronously and in this case \a on_data_sent() will be called.
412  *
413  * @param stun_sock     The STUN transport instance.
414  * @param send_key      Optional send key for sending the packet down to
415  *                      the ioqueue. This value will be given back to
416  *                      \a on_data_sent() callback
417  * @param pkt           The data/packet to be sent to peer.
418  * @param pkt_len       Length of the data.
419  * @param flag          pj_ioqueue_sendto() flag.
420  * @param dst_addr      The remote address.
421  * @param addr_len      Length of the address.
422  *
423  * @return              PJ_SUCCESS if data has been sent immediately, or
424  *                      PJ_EPENDING if data cannot be sent immediately. In
425  *                      this case the \a on_data_sent() callback will be
426  *                      called when data is actually sent. Any other return
427  *                      value indicates error condition.
428  */ 
429 PJ_DECL(pj_status_t) pj_stun_sock_sendto(pj_stun_sock *stun_sock,
430                                          pj_ioqueue_op_key_t *send_key,
431                                          const void *pkt,
432                                          unsigned pkt_len,
433                                          unsigned flag,
434                                          const pj_sockaddr_t *dst_addr,
435                                          unsigned addr_len);
436
437 /**
438  * @}
439  */
440
441
442 PJ_END_DECL
443
444
445 #endif  /* __PJNATH_STUN_SOCK_H__ */
446