X-Git-Url: http://sjero.net/git/?p=linphone;a=blobdiff_plain;f=coreapi%2Flinphone_tunnel.h;h=f02baab5473ee6d8f7f29b03808eb253667b47a8;hp=6a2d5218e00071540be3ead2630667fa9049be2f;hb=5f0d5793b7e65a518076de6f8e253770503f8824;hpb=92c2160888d192a46613905b31b7e78de247651c

diff --git a/coreapi/linphone_tunnel.h b/coreapi/linphone_tunnel.h
index 6a2d5218..f02baab5 100644
--- a/coreapi/linphone_tunnel.h
+++ b/coreapi/linphone_tunnel.h
@@ -23,63 +23,203 @@
  *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
  
-#ifndef LINPHONETUNNELMANAGER_H
-#define LINPHONETUNNELMANAGER_H
+#ifndef LINPHONETUNNEL_H
+#define LINPHONETUNNEL_H
 
 #include "linphonecore.h"
 
+/**
+ * @addtogroup tunnel
+ * @{
+**/
+
+	/**
+	 * This set of methods enhance  LinphoneCore functionalities in order to provide an easy to use API to
+	 * - provision tunnel servers ip addresses and ports. This functionality is an option not implemented under GPL.
+	 * - start/stop the tunneling service
+	 * - perform auto-detection whether tunneling is required, based on a test of sending/receiving a flow of UDP packets.
+	 *
+	 * It takes in charge automatically the SIP registration procedure when connecting or disconnecting to a tunnel server.
+	 * No other action on LinphoneCore is required to enable full operation in tunnel mode.
+	**/
+
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
-typedef void (*LogHandler)(int log_level, const char *str, va_list l);
+typedef struct _LinphoneTunnelConfig LinphoneTunnelConfig;
 
-void linphone_tunnel_add_server(LinphoneTunnel *tunnel, const char *host, int port);
-void linphone_tunnel_add_server_and_mirror(LinphoneTunnel *tunnel, const char *host, int port, int remote_udp_mirror, int delay);
-void linphone_tunnel_clean_servers(LinphoneTunnel *tunnel);
-void linphone_tunnel_enable(LinphoneTunnel *tunnel, bool_t enabled);
-bool_t linphone_tunnel_enabled(LinphoneTunnel *tunnel);
-void linphone_tunnel_enable_logs(LinphoneTunnel *tunnel, bool_t enabled);
-void linphone_tunnel_enable_logs_with_handler(LinphoneTunnel *tunnel, bool_t enabled, LogHandler logHandler);
-void linphone_tunnel_reconnect(LinphoneTunnel *tunnel);
-void linphone_tunnel_auto_detect(LinphoneTunnel *tunnel);
-void linphone_tunnel_set_http_proxy_auth_info(LinphoneTunnel*tunnel, const char* username,const char* passwd);
+/**
+ * Create a new tunnel configuration
+ */
+LinphoneTunnelConfig *linphone_tunnel_config_new();
+
+/**
+ * Set address of server.
+ *
+ * @param tunnel configuration object
+ * @param host tunnel server ip address
+ */
+void linphone_tunnel_config_set_host(LinphoneTunnelConfig *tunnel, const char *host);
+
+/**
+ * Get address of server.
+ *
+ * @param tunnel configuration object
+ */
+const char *linphone_tunnel_config_get_host(const LinphoneTunnelConfig *tunnel);
+
+/**
+ * Set tls port of server.
+ *
+ * @param tunnel configuration object
+ * @param port tunnel server tls port, recommended value is 443
+ */
+void linphone_tunnel_config_set_port(LinphoneTunnelConfig *tunnel, int port);
 
+/**
+ * Get tls port of server.
+ *
+ * @param tunnel configuration object
+ */
+int linphone_tunnel_config_get_port(const LinphoneTunnelConfig *tunnel);
 
 /**
- * LinphoneTunnelState describes the tunnel activation states.
+ * Set the remote port on the tunnel server side used to test udp reachability. 
+ *
+ * @param tunnel configuration object
+ * @param remote_udp_mirror_port remote port on the tunnel server side used to test udp reachability, set to -1 to disable the feature
  */
-typedef enum _LinphoneTunnelState{
-	LinphoneTunnelDisabled, /**<The tunnel is always on */
-	LinphoneTunnelEnabled, /**<The tunnel is always off */
-	LinphoneTunnelAuto /**<The tunnel is active if needed */
-}LinphoneTunnelState;
+void linphone_tunnel_config_set_remote_udp_mirror_port(LinphoneTunnelConfig *tunnel, int remote_udp_mirror_port);
 
 /**
- * Set tunnel addresses.
+ * Get the remote port on the tunnel server side used to test udp reachability.
+ *
+ * @param tunnel configuration object
+ */
+int linphone_tunnel_config_get_remote_udp_mirror_port(const LinphoneTunnelConfig *tunnel);
+
+/**
+ * Set the udp packet round trip delay in ms for a tunnel configuration.
+ *
+ * @param tunnel configuration object
+ * @param delay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms.
+ */
+void linphone_tunnel_config_set_delay(LinphoneTunnelConfig *tunnel, int delay);
+
+/**
+ * Get the udp packet round trip delay in ms for a tunnel configuration.
+ * 
+ * @param tunnel configuration object
+ */
+int linphone_tunnel_config_get_delay(const LinphoneTunnelConfig *tunnel);
+
+/**
+ * Destroy a tunnel configuration
+ *
+ * @param tunnel configuration object
+ */
+void linphone_tunnel_config_destroy(LinphoneTunnelConfig *tunnel);
+
+/**
+ * Add tunnel server configuration
+ *
+ * @param tunnel object
+ * @param tunnel_config object
+ */
+void linphone_tunnel_add_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
+
+/**
+ * Remove tunnel server configuration
+ * 
+ * @param tunnel object
+ * @param tunnel_config object
+ */
+void linphone_tunnel_remove_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
+
+/**
+ * @param  tunnel object
+ * returns a string of space separated list of host:port of tunnel server addresses
+ * */
+const MSList *linphone_tunnel_get_servers(LinphoneTunnel *tunnel);
+
+/**
+ * @param  tunnel object
+ * Removes all tunnel server address previously entered with addServer()
 **/
-void linphone_tunnel_set_server_addresses(LinphoneTunnel *tunnel, const char *lists);
+void linphone_tunnel_clean_servers(LinphoneTunnel *tunnel);
 
 /**
- * Get tunnel addresses.
+ * Sets whether tunneling of SIP and RTP is required.
+ * @param  tunnel object
+ * @param enabled If true enter in tunneled mode, if false exits from tunneled mode.
+ * The TunnelManager takes care of refreshing SIP registration when switching on or off the tunneled mode.
+ *
 **/
-const char *linphone_tunnel_get_server_addresses(LinphoneTunnel *tunnel);
+void linphone_tunnel_enable(LinphoneTunnel *tunnel, bool_t enabled);
 
 /**
- * Set tunnel state.
+ * @param  tunnel object
+ * Returns a boolean indicating whether tunneled operation is enabled.
 **/
-void linphone_tunnel_set_state(LinphoneTunnel *tunnel, LinphoneTunnelState state);
+bool_t linphone_tunnel_enabled(LinphoneTunnel *tunnel);
 
 /**
- * Get tunnel state.
+ * @param  tunnel object
+ * Returns a boolean indicating whether tunnel is connected successfully.
 **/
-LinphoneTunnelState linphone_tunnel_get_state(LinphoneTunnel *tunnel);
+bool_t linphone_tunnel_connected(LinphoneTunnel *tunnel);
 
+/**
+ * @param  tunnel object
+ * Forces reconnection to the tunnel server.
+ * This method is useful when the device switches from wifi to Edge/3G or vice versa. In most cases the tunnel client socket
+ * won't be notified promptly that its connection is now zombie, so it is recommended to call this method that will cause
+ * the lost connection to be closed and new connection to be issued.
+**/
+void linphone_tunnel_reconnect(LinphoneTunnel *tunnel);
+
+/**
+ * Start tunnel need detection.
+ * @param  tunnel object
+ * In auto detect mode, the tunnel manager try to establish a real time rtp cummunication with the tunnel server on  specified port.
+ *<br>In case of success, the tunnel is automatically turned off. Otherwise, if no udp commmunication is feasible, tunnel mode is turned on.
+ *<br> Call this method each time to run the auto detection algorithm
+ */
+void linphone_tunnel_auto_detect(LinphoneTunnel *tunnel);
+
+/**
+ * Set an optional http proxy to go through when connecting to tunnel server.
+ * @param tunnel LinphoneTunnel object
+ * @param host Http proxy host.
+ * @param port http proxy port.
+ * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
+ * @param password optional http proxy password. Use NULL if not needed.
+ **/
+void linphone_tunnel_set_http_proxy(LinphoneTunnel *tunnel, const char *host, int port, const char* username,const char* passwd);
+
+/**
+ * Retrieve optional http proxy configuration previously set with linphone_tunnel_set_http_proxy().
+ * @param tunnel LinphoneTunnel object
+ * @param host Http proxy host.
+ * @param port http proxy port.
+ * @param username optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
+ * @param password optional http proxy password. Use NULL if not needed.
+ **/
+void linphone_tunnel_get_http_proxy(LinphoneTunnel*tunnel,const char **host, int *port, const char **username, const char **passwd);
+
+void linphone_tunnel_set_http_proxy_auth_info(LinphoneTunnel*tunnel, const char* username,const char* passwd);
+
+
+/**
+ * @}
+**/
 
 #ifdef __cplusplus
 }
 #endif
 
 
-#endif
+#endif //LINPHONETUNNEL_H
+