sjero.net Git - linphone/blob - coreapi/linphone_tunnel.h

   1 /***************************************************************************
   2  *            linphone_tunnel.h
   3  *
   4  *  Fri Dec 9, 2011
   5  *  Copyright  2011  Belledonne Communications
   6  *  Author: Guillaume Beraudo
   7  *  Email: guillaume dot beraudo at linphone dot org
   8  ****************************************************************************/
   9
  10 /*
  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.
  15  *
  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.
  20  *
  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.
  24  */
  25
  26 #ifndef LINPHONETUNNEL_H
  27 #define LINPHONETUNNEL_H
  28
  29 #include "linphonecore.h"
  30
  31 /**
  32  * @addtogroup tunnel
  33  * @{
  34 **/
  35
  36         /**
  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.
  41          *
  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.
  44         **/
  45
  46 #ifdef __cplusplus
  47 extern "C"
  48 {
  49 #endif
  50
  51 typedef struct _LinphoneTunnelConfig LinphoneTunnelConfig;
  52
  53 /**
  54  * Create a new tunnel configuration
  55  */
  56 LinphoneTunnelConfig *linphone_tunnel_config_new();
  57
  58 /**
  59  * Set address of server.
  60  *
  61  * @param tunnel configuration object
  62  * @param host tunnel server ip address
  63  */
  64 void linphone_tunnel_config_set_host(LinphoneTunnelConfig *tunnel, const char *host);
  65
  66 /**
  67  * Get address of server.
  68  *
  69  * @param tunnel configuration object
  70  */
  71 const char *linphone_tunnel_config_get_host(const LinphoneTunnelConfig *tunnel);
  72
  73 /**
  74  * Set tls port of server.
  75  *
  76  * @param tunnel configuration object
  77  * @param port tunnel server tls port, recommended value is 443
  78  */
  79 void linphone_tunnel_config_set_port(LinphoneTunnelConfig *tunnel, int port);
  80
  81 /**
  82  * Get tls port of server.
  83  *
  84  * @param tunnel configuration object
  85  */
  86 int linphone_tunnel_config_get_port(const LinphoneTunnelConfig *tunnel);
  87
  88 /**
  89  * Set the remote port on the tunnel server side used to test udp reachability.
  90  *
  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
  93  */
  94 void linphone_tunnel_config_set_remote_udp_mirror_port(LinphoneTunnelConfig *tunnel, int remote_udp_mirror_port);
  95
  96 /**
  97  * Get the remote port on the tunnel server side used to test udp reachability.
  98  *
  99  * @param tunnel configuration object
 100  */
 101 int linphone_tunnel_config_get_remote_udp_mirror_port(const LinphoneTunnelConfig *tunnel);
 102
 103 /**
 104  * Set the udp packet round trip delay in ms for a tunnel configuration.
 105  *
 106  * @param tunnel configuration object
 107  * @param delay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms.
 108  */
 109 void linphone_tunnel_config_set_delay(LinphoneTunnelConfig *tunnel, int delay);
 110
 111 /**
 112  * Get the udp packet round trip delay in ms for a tunnel configuration.
 113  *
 114  * @param tunnel configuration object
 115  */
 116 int linphone_tunnel_config_get_delay(const LinphoneTunnelConfig *tunnel);
 117
 118 /**
 119  * Destroy a tunnel configuration
 120  *
 121  * @param tunnel configuration object
 122  */
 123 void linphone_tunnel_config_destroy(LinphoneTunnelConfig *tunnel);
 124
 125 /**
 126  * Add tunnel server configuration
 127  *
 128  * @param tunnel object
 129  * @param tunnel_config object
 130  */
 131 void linphone_tunnel_add_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
 132
 133 /**
 134  * Remove tunnel server configuration
 135  *
 136  * @param tunnel object
 137  * @param tunnel_config object
 138  */
 139 void linphone_tunnel_remove_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
 140
 141 /**
 142  * @param  tunnel object
 143  * returns a string of space separated list of host:port of tunnel server addresses
 144  * */
 145 const MSList *linphone_tunnel_get_servers(LinphoneTunnel *tunnel);
 146
 147 /**
 148  * @param  tunnel object
 149  * Removes all tunnel server address previously entered with addServer()
 150 **/
 151 void linphone_tunnel_clean_servers(LinphoneTunnel *tunnel);
 152
 153 /**
 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.
 158  *
 159 **/
 160 void linphone_tunnel_enable(LinphoneTunnel *tunnel, bool_t enabled);
 161
 162 /**
 163  * @param  tunnel object
 164  * Returns a boolean indicating whether tunneled operation is enabled.
 165 **/
 166 bool_t linphone_tunnel_enabled(LinphoneTunnel *tunnel);
 167
 168 /**
 169  * @param  tunnel object
 170  * Forces reconnection to the tunnel server.
 171  * This method is useful when the device switches from wifi to Edge/3G or vice versa. In most cases the tunnel client socket
 172  * won't be notified promptly that its connection is now zombie, so it is recommended to call this method that will cause
 173  * the lost connection to be closed and new connection to be issued.
 174 **/
 175 void linphone_tunnel_reconnect(LinphoneTunnel *tunnel);
 176
 177 /**
 178  * Start tunnel need detection.
 179  * @param  tunnel object
 180  * In auto detect mode, the tunnel manager try to establish a real time rtp cummunication with the tunnel server on  specified port.
 181  *<br>In case of success, the tunnel is automatically turned off. Otherwise, if no udp commmunication is feasible, tunnel mode is turned on.
 182  *<br> Call this method each time to run the auto detection algorithm
 183  */
 184 void linphone_tunnel_auto_detect(LinphoneTunnel *tunnel);
 185
 186 /**
 187  * Set an optional http proxy to go through when connecting to tunnel server.
 188  * @param tunnel LinphoneTunnel object
 189  * @param host Http proxy host.
 190  * @param port http proxy port.
 191  * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
 192  * @param password optional http proxy password. Use NULL if not needed.
 193  **/
 194 void linphone_tunnel_set_http_proxy(LinphoneTunnel *tunnel, const char *host, int port, const char* username,const char* passwd);
 195
 196 /**
 197  * Retrieve optional http proxy configuration previously set with linphone_tunnel_set_http_proxy().
 198  * @param tunnel LinphoneTunnel object
 199  * @param host Http proxy host.
 200  * @param port http proxy port.
 201  * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
 202  * @param password optional http proxy password. Use NULL if not needed.
 203  **/
 204 void linphone_tunnel_get_http_proxy(LinphoneTunnel*tunnel,const char **host, int *port, const char **username, const char **passwd);
 205
 206 void linphone_tunnel_set_http_proxy_auth_info(LinphoneTunnel*tunnel, const char* username,const char* passwd);
 207
 208
 209 /**
 210  * @}
 211 **/
 212
 213 #ifdef __cplusplus
 214 }
 215 #endif
 216
 217
 218 #endif //LINPHONETUNNEL_H
 219