Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / transport_ice.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 __PJMEDIA_TRANSPORT_ICE_H__
21 #define __PJMEDIA_TRANSPORT_ICE_H__
22
23
24 /**
25  * @file transport_ice.h
26  * @brief ICE capable media transport.
27  */
28
29 #include <pjmedia/stream.h>
30 #include <pjnath/ice_strans.h>
31
32
33 /**
34  * @defgroup PJMEDIA_TRANSPORT_ICE ICE Media Transport 
35  * @ingroup PJMEDIA_TRANSPORT
36  * @brief Interactive Connectivity Establishment (ICE) transport
37  * @{
38  *
39  * This describes the implementation of media transport using
40  * Interactive Connectivity Establishment (ICE) protocol.
41  */
42
43 PJ_BEGIN_DECL
44
45
46 /**
47  * Structure containing callbacks to receive ICE notifications.
48  */
49 typedef struct pjmedia_ice_cb
50 {
51     /**
52      * This callback will be called when ICE negotiation completes.
53      *
54      * @param tp        PJMEDIA ICE transport.
55      * @param op        The operation
56      * @param status    Operation status.
57      */
58     void    (*on_ice_complete)(pjmedia_transport *tp,
59                                pj_ice_strans_op op,
60                                pj_status_t status);
61
62 } pjmedia_ice_cb;
63
64
65 /**
66  * This structure specifies ICE transport specific info. This structure
67  * will be filled in media transport specific info.
68  */
69 typedef struct pjmedia_ice_transport_info
70 {
71     /**
72      * ICE sesion state.
73      */
74     pj_ice_strans_state sess_state;
75
76     /**
77      * Session role.
78      */
79     pj_ice_sess_role role;
80
81     /**
82      * Number of components in the component array. Before ICE negotiation
83      * is complete, the number represents the number of components of the
84      * local agent. After ICE negotiation has been completed successfully,
85      * the number represents the number of common components between local
86      * and remote agents.
87      */
88     unsigned comp_cnt;
89
90     /**
91      * Array of ICE components. Typically the first element denotes RTP and
92      * second element denotes RTCP.
93      */
94     struct
95     {
96         /**
97          * Local candidate type.
98          */
99         pj_ice_cand_type    lcand_type;
100
101         /**
102          * The local address.
103          */
104         pj_sockaddr         lcand_addr;
105
106         /**
107          * Remote candidate type.
108          */
109         pj_ice_cand_type    rcand_type;
110
111         /**
112          * Remote address.
113          */
114         pj_sockaddr         rcand_addr;
115
116     } comp[2];
117
118 } pjmedia_ice_transport_info;
119
120
121 /**
122  * Options that can be specified when creating ICE transport.
123  */
124 enum pjmedia_transport_ice_options
125 {
126     /**
127      * Normally when remote doesn't use ICE, the ICE transport will 
128      * continuously check the source address of incoming packets to see 
129      * if it is different than the configured remote address, and switch 
130      * the remote address to the source address of the packet if they 
131      * are different after several packets are received.
132      * Specifying this option will disable this feature.
133      */
134     PJMEDIA_ICE_NO_SRC_ADDR_CHECKING = 1
135 };
136
137
138 /**
139  * Create the Interactive Connectivity Establishment (ICE) media transport
140  * using the specified configuration. When STUN or TURN (or both) is used,
141  * the creation operation will complete asynchronously, when STUN resolution
142  * and TURN allocation completes. When the initialization completes, the
143  * \a on_ice_complete() complete will be called with \a op parameter equal
144  * to PJ_ICE_STRANS_OP_INIT.
145  *
146  * In addition, this transport will also notify the application about the
147  * result of ICE negotiation, also in \a on_ice_complete() callback. In this
148  * case the callback will be called with \a op parameter equal to
149  * PJ_ICE_STRANS_OP_NEGOTIATION.
150  *
151  * Other than this, application should use the \ref PJMEDIA_TRANSPORT API
152  * to manipulate this media transport.
153  *
154  * @param endpt         The media endpoint.
155  * @param name          Optional name to identify this ICE media transport
156  *                      for logging purposes.
157  * @param comp_cnt      Number of components to be created.
158  * @param cfg           Pointer to configuration settings.
159  * @param cb            Optional structure containing ICE specific callbacks.
160  * @param p_tp          Pointer to receive the media transport instance.
161  *
162  * @return              PJ_SUCCESS on success, or the appropriate error code.
163  */
164 PJ_DECL(pj_status_t) pjmedia_ice_create(pjmedia_endpt *endpt,
165                                         const char *name,
166                                         unsigned comp_cnt,
167                                         const pj_ice_strans_cfg *cfg,
168                                         const pjmedia_ice_cb *cb,
169                                         pjmedia_transport **p_tp);
170
171
172 /**
173  * The same as #pjmedia_ice_create() with additional \a options param.
174  *
175  * @param endpt         The media endpoint.
176  * @param name          Optional name to identify this ICE media transport
177  *                      for logging purposes.
178  * @param comp_cnt      Number of components to be created.
179  * @param cfg           Pointer to configuration settings.
180  * @param cb            Optional structure containing ICE specific callbacks.
181  * @param options       Options, see #pjmedia_transport_ice_options.
182  * @param p_tp          Pointer to receive the media transport instance.
183  *
184  * @return              PJ_SUCCESS on success, or the appropriate error code.
185  */
186 PJ_DECL(pj_status_t) pjmedia_ice_create2(pjmedia_endpt *endpt,
187                                          const char *name,
188                                          unsigned comp_cnt,
189                                          const pj_ice_strans_cfg *cfg,
190                                          const pjmedia_ice_cb *cb,
191                                          unsigned options,
192                                          pjmedia_transport **p_tp);
193
194 /**
195  * The same as #pjmedia_ice_create2() with additional \a user_data param.
196  *
197  * @param endpt         The media endpoint.
198  * @param name          Optional name to identify this ICE media transport
199  *                      for logging purposes.
200  * @param comp_cnt      Number of components to be created.
201  * @param cfg           Pointer to configuration settings.
202  * @param cb            Optional structure containing ICE specific callbacks.
203  * @param options       Options, see #pjmedia_transport_ice_options.
204  * @param user_data     User data to be attached to the transport.
205  * @param p_tp          Pointer to receive the media transport instance.
206  *
207  * @return              PJ_SUCCESS on success, or the appropriate error code.
208  */
209 PJ_DECL(pj_status_t) pjmedia_ice_create3(pjmedia_endpt *endpt,
210                                          const char *name,
211                                          unsigned comp_cnt,
212                                          const pj_ice_strans_cfg *cfg,
213                                          const pjmedia_ice_cb *cb,
214                                          unsigned options,
215                                          void *user_data,
216                                          pjmedia_transport **p_tp);
217
218 PJ_END_DECL
219
220
221 /**
222  * @}
223  */
224
225
226 #endif  /* __PJMEDIA_TRANSPORT_ICE_H__ */
227
228