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 LINPHONETUNNELMANAGER_H
  27 #define LINPHONETUNNELMANAGER_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 /**
  52  * Add a tunnel server. At least one should be provided to be able to connect.
  53  * When several addresses are provided, the tunnel client may try each of them until it gets connected.
  54  * @param  tunnel object
  55  * @param host server ip address
  56  * @param port tunnel server tls port, recommended value is 443
  57  */
  58 void linphone_tunnel_add_server(LinphoneTunnel *tunnel, const char *host, int port);
  59 /**
  60  *Add tunnel server with auto detection capabilities
  61  *
  62  * @param  tunnel object
  63  * @param host tunnel server ip address
  64  * @param port tunnel server tls port, recommended value is 443
  65  * @param remote_udp_mirror_port remote port on the tunnel server side used to test udp reachability
  66  * @param delay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms.
  67  */
  68 void linphone_tunnel_add_server_and_mirror(LinphoneTunnel *tunnel, const char *host, int port, int remote_udp_mirror_port, int delay);
  69 /**
  70  * @param  tunnel object
  71  * returns a string of space separated list of host:port of tunnel server addresses
  72  * */
  73 char *linphone_tunnel_get_servers(LinphoneTunnel *tunnel);
  74 /**
  75  * @param  tunnel object
  76  * Removes all tunnel server address previously entered with addServer()
  77 **/
  78 void linphone_tunnel_clean_servers(LinphoneTunnel *tunnel);
  79 /**
  80  * Sets whether tunneling of SIP and RTP is required.
  81  * @param  tunnel object
  82  * @param enabled If true enter in tunneled mode, if false exits from tunneled mode.
  83  * The TunnelManager takes care of refreshing SIP registration when switching on or off the tunneled mode.
  84  *
  85 **/
  86 void linphone_tunnel_enable(LinphoneTunnel *tunnel, bool_t enabled);
  87 /**
  88  * @param  tunnel object
  89  * Returns a boolean indicating whether tunneled operation is enabled.
  90 **/
  91 bool_t linphone_tunnel_enabled(LinphoneTunnel *tunnel);
  92 /**
  93  * @param  tunnel object
  94  * Forces reconnection to the tunnel server.
  95  * This method is useful when the device switches from wifi to Edge/3G or vice versa. In most cases the tunnel client socket
  96  * won't be notified promptly that its connection is now zombie, so it is recommended to call this method that will cause
  97  * the lost connection to be closed and new connection to be issued.
  98 **/
  99 void linphone_tunnel_reconnect(LinphoneTunnel *tunnel);
 100 /**
 101  * Start tunnel need detection.
 102  * @param  tunnel object
 103  * In auto detect mode, the tunnel manager try to establish a real time rtp cummunication with the tunnel server on  specified port.
 104  *<br>In case of success, the tunnel is automatically turned off. Otherwise, if no udp commmunication is feasible, tunnel mode is turned on.
 105  *<br> Call this method each time to run the auto detection algorithm
 106  */
 107 void linphone_tunnel_auto_detect(LinphoneTunnel *tunnel);
 108
 109 /**
 110  * Set an optional http proxy to go through when connecting to tunnel server.
 111  * @param tunnel LinphoneTunnel object
 112  * @param host Http proxy host.
 113  * @param port http proxy port.
 114  * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
 115  * @param password optional http proxy password. Use NULL if not needed.
 116  **/
 117 void linphone_tunnel_set_http_proxy(LinphoneTunnel *tunnel, const char *host, int port, const char* username,const char* passwd);
 118
 119 /**
 120  * Retrieve optional http proxy configuration previously set with linphone_tunnel_set_http_proxy().
 121  * @param tunnel LinphoneTunnel object
 122  * @param host Http proxy host.
 123  * @param port http proxy port.
 124  * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
 125  * @param password optional http proxy password. Use NULL if not needed.
 126  **/
 127 void linphone_tunnel_get_http_proxy(LinphoneTunnel*tunnel,const char **host, int *port, const char **username, const char **passwd);
 128
 129 void linphone_tunnel_set_http_proxy_auth_info(LinphoneTunnel*tunnel, const char* username,const char* passwd);
 130
 131
 132 void linphone_tunnel_enable_logs(LinphoneTunnel *tunnel, bool_t enabled);
 133
 134 /**
 135  * @}
 136 **/
 137
 138 #ifdef __cplusplus
 139 }
 140 #endif
 141
 142
 143 #endif
 144