1 /***************************************************************************
5 * Copyright 2011 Belledonne Communications
6 * Author: Guillaume Beraudo
7 * Email: guillaume dot beraudo at linphone dot org
8 ****************************************************************************/
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 #ifndef LINPHONETUNNEL_H
27 #define LINPHONETUNNEL_H
29 #include "linphonecore.h"
37 * This set of methods enhance LinphoneCore functionalities in order to provide an easy to use API to
38 * - provision tunnel servers ip addresses and ports. This functionality is an option not implemented under GPL.
39 * - start/stop the tunneling service
40 * - perform auto-detection whether tunneling is required, based on a test of sending/receiving a flow of UDP packets.
42 * It takes in charge automatically the SIP registration procedure when connecting or disconnecting to a tunnel server.
43 * No other action on LinphoneCore is required to enable full operation in tunnel mode.
51 typedef struct _LinphoneTunnelConfig LinphoneTunnelConfig;
54 * Create a new tunnel configuration
56 LinphoneTunnelConfig *linphone_tunnel_config_new();
59 * Set address of server.
61 * @param tunnel configuration object
62 * @param host tunnel server ip address
64 void linphone_tunnel_config_set_host(LinphoneTunnelConfig *tunnel, const char *host);
67 * Get address of server.
69 * @param tunnel configuration object
71 const char *linphone_tunnel_config_get_host(const LinphoneTunnelConfig *tunnel);
74 * Set tls port of server.
76 * @param tunnel configuration object
77 * @param port tunnel server tls port, recommended value is 443
79 void linphone_tunnel_config_set_port(LinphoneTunnelConfig *tunnel, int port);
82 * Get tls port of server.
84 * @param tunnel configuration object
86 int linphone_tunnel_config_get_port(const LinphoneTunnelConfig *tunnel);
89 * Set the remote port on the tunnel server side used to test udp reachability.
91 * @param tunnel configuration object
92 * @param remote_udp_mirror_port remote port on the tunnel server side used to test udp reachability, set to -1 to disable the feature
94 void linphone_tunnel_config_set_remote_udp_mirror_port(LinphoneTunnelConfig *tunnel, int remote_udp_mirror_port);
97 * Get the remote port on the tunnel server side used to test udp reachability.
99 * @param tunnel configuration object
101 int linphone_tunnel_config_get_remote_udp_mirror_port(const LinphoneTunnelConfig *tunnel);
104 * Set the udp packet round trip delay in ms for a tunnel configuration.
106 * @param tunnel configuration object
107 * @param delay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms.
109 void linphone_tunnel_config_set_delay(LinphoneTunnelConfig *tunnel, int delay);
112 * Get the udp packet round trip delay in ms for a tunnel configuration.
114 * @param tunnel configuration object
116 int linphone_tunnel_config_get_delay(const LinphoneTunnelConfig *tunnel);
119 * Destroy a tunnel configuration
121 * @param tunnel configuration object
123 void linphone_tunnel_config_destroy(LinphoneTunnelConfig *tunnel);
126 * Add tunnel server configuration
128 * @param tunnel object
129 * @param tunnel_config object
131 void linphone_tunnel_add_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
134 * Remove tunnel server configuration
136 * @param tunnel object
137 * @param tunnel_config object
139 void linphone_tunnel_remove_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
142 * @param tunnel object
143 * returns a string of space separated list of host:port of tunnel server addresses
145 const MSList *linphone_tunnel_get_servers(LinphoneTunnel *tunnel);
148 * @param tunnel object
149 * Removes all tunnel server address previously entered with addServer()
151 void linphone_tunnel_clean_servers(LinphoneTunnel *tunnel);
154 * Sets whether tunneling of SIP and RTP is required.
155 * @param tunnel object
156 * @param enabled If true enter in tunneled mode, if false exits from tunneled mode.
157 * The TunnelManager takes care of refreshing SIP registration when switching on or off the tunneled mode.
160 void linphone_tunnel_enable(LinphoneTunnel *tunnel, bool_t enabled);
163 * @param tunnel object
164 * Returns a boolean indicating whether tunneled operation is enabled.
166 bool_t linphone_tunnel_enabled(LinphoneTunnel *tunnel);
169 * @param tunnel object
170 * Returns a boolean indicating whether tunnel is connected successfully.
172 bool_t linphone_tunnel_connected(LinphoneTunnel *tunnel);
175 * @param tunnel object
176 * Forces reconnection to the tunnel server.
177 * This method is useful when the device switches from wifi to Edge/3G or vice versa. In most cases the tunnel client socket
178 * won't be notified promptly that its connection is now zombie, so it is recommended to call this method that will cause
179 * the lost connection to be closed and new connection to be issued.
181 void linphone_tunnel_reconnect(LinphoneTunnel *tunnel);
184 * Start tunnel need detection.
185 * @param tunnel object
186 * In auto detect mode, the tunnel manager try to establish a real time rtp cummunication with the tunnel server on specified port.
187 *<br>In case of success, the tunnel is automatically turned off. Otherwise, if no udp commmunication is feasible, tunnel mode is turned on.
188 *<br> Call this method each time to run the auto detection algorithm
190 void linphone_tunnel_auto_detect(LinphoneTunnel *tunnel);
193 * Set an optional http proxy to go through when connecting to tunnel server.
194 * @param tunnel LinphoneTunnel object
195 * @param host Http proxy host.
196 * @param port http proxy port.
197 * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
198 * @param password optional http proxy password. Use NULL if not needed.
200 void linphone_tunnel_set_http_proxy(LinphoneTunnel *tunnel, const char *host, int port, const char* username,const char* passwd);
203 * Retrieve optional http proxy configuration previously set with linphone_tunnel_set_http_proxy().
204 * @param tunnel LinphoneTunnel object
205 * @param host Http proxy host.
206 * @param port http proxy port.
207 * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
208 * @param password optional http proxy password. Use NULL if not needed.
210 void linphone_tunnel_get_http_proxy(LinphoneTunnel*tunnel,const char **host, int *port, const char **username, const char **passwd);
212 void linphone_tunnel_set_http_proxy_auth_info(LinphoneTunnel*tunnel, const char* username,const char* passwd);
224 #endif //LINPHONETUNNEL_H