More ticket #485: implementation of TURN UDP client session

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@1862 74dad513-b988-da41-8d7b-12977e46ad98

4 files changed, 286 insertions, 20 deletions

diff --git a/pjnath/include/pjnath/errno.h b/pjnath/include/pjnath/errno.h
index 1f763fc1..56763916 100644
--- a/pjnath/include/pjnath/errno.h
+++ b/pjnath/include/pjnath/errno.h
@@ -50,20 +50,24 @@
 
 /**
  * @hideinitializer
+ * Invalid STUN message
+ */
+#define PJNATH_EINSTUNMSG	    (PJNATH_ERRNO_START+1)  /* 370001 */
+/**
+ * @hideinitializer
  * Invalid STUN message length.
  */
-#define PJNATH_EINSTUNMSGLEN	    (PJNATH_ERRNO_START+1)  /* 370001 */
+#define PJNATH_EINSTUNMSGLEN	    (PJNATH_ERRNO_START+2)  /* 370002 */
 /**
  * @hideinitializer
  * Invalid or unexpected STUN message type
  */
-#define	PJNATH_EINSTUNMSGTYPE	    (PJNATH_ERRNO_START+2)  /* 370002 */
+#define	PJNATH_EINSTUNMSGTYPE	    (PJNATH_ERRNO_START+3)  /* 370003 */
 /**
  * @hideinitializer
  * STUN transaction has timed out
  */
-#define PJNATH_ESTUNTIMEDOUT	    (PJNATH_ERRNO_START+3)  /* 370003 */
-
+#define PJNATH_ESTUNTIMEDOUT	    (PJNATH_ERRNO_START+4)  /* 370004 */
 
 
 /**
@@ -173,6 +177,17 @@
 #define PJNATH_EICENOHOSTCAND	    (PJNATH_ERRNO_START+92) /* 370092 */
 
 
+/************************************************************
+ * TURN ERROR CODES
+ ***********************************************************/
+/**
+ * @hideinitializer
+ * Invalid or unsupported TURN transport.
+ */
+#define PJNATH_ETURNINTP	    (PJNATH_ERRNO_START+120) /* 370120 */
+
+
+
 /**
  * @}
  */
diff --git a/pjnath/include/pjnath/stun_session.h b/pjnath/include/pjnath/stun_session.h
index 2f096d57..b28763ac 100644
--- a/pjnath/include/pjnath/stun_session.h
+++ b/pjnath/include/pjnath/stun_session.h
@@ -112,7 +112,7 @@ typedef struct pj_stun_session_cb
      *			    Note that when the status is not success, the
      *			    response may contain non-NULL value if the 
      *			    response contains STUN ERROR-CODE attribute.
-     * @param request	    The original STUN request.
+     * @param tdata	    The original STUN request.
      * @param response	    The response message, on successful transaction,
      *			    or otherwise MAY BE NULL if status is not success.
      *			    Note that when the status is not success, this
@@ -224,6 +224,22 @@ PJ_DECL(pj_status_t) pj_stun_session_set_user_data(pj_stun_session *sess,
 PJ_DECL(void*) pj_stun_session_get_user_data(pj_stun_session *sess);
 
 /**
+ * Change the lock object used by the STUN session. By default, the STUN
+ * session uses a mutex to protect its internal data. If application already
+ * protects access to STUN session with higher layer lock, it may disable
+ * the mutex protection in the STUN session by changing the STUN session
+ * lock to a NULL mutex.
+ *
+ * @param sess	    The STUN session instance.
+ * @param lock	    New lock instance to be used by the STUN session.
+ * @param auto_del  Specify whether STUN session should destroy this
+ *		    lock instance when it's destroyed.
+ */
+PJ_DECL(pj_status_t) pj_stun_session_set_lock(pj_stun_session *sess,
+					      pj_lock_t *lock,
+					      pj_bool_t auto_del);
+
+/**
  * Set server name to be included in all response.
  *
  * @param sess	    The STUN session instance.
diff --git a/pjnath/include/pjnath/turn_session.h b/pjnath/include/pjnath/turn_session.h
index 19260b77..bb00e0de 100644
--- a/pjnath/include/pjnath/turn_session.h
+++ b/pjnath/include/pjnath/turn_session.h
@@ -48,15 +48,73 @@ typedef struct pj_turn_session pj_turn_session;
 #define PJ_TURN_CHANNEL_MAX	    0xFFFE  /* inclusive */
 #define PJ_TURN_NO_TIMEOUT	    ((long)0x7FFFFFFF)
 #define PJ_TURN_MAX_PKT_LEN	    3000
-#define PJ_TURN_PERM_TIMEOUT	    300
-#define PJ_TURN_CHANNEL_TIMEOUT	    600
+#define PJ_TURN_PERM_TIMEOUT	    300	/* Must be greater than REFRESH_SEC_BEFORE */
+#define PJ_TURN_CHANNEL_TIMEOUT	    600	/* Must be greater than REFRESH_SEC_BEFORE */
+#define PJ_TURN_REFRESH_SEC_BEFORE  60
+#define PJ_TURN_KEEP_ALIVE_SEC	    15
+#define PJ_TURN_PEER_HTABLE_SIZE    8
 
 
-/** Transport types */
-enum {
+/** TURN transport types */
+typedef enum pj_turn_tp_type
+{
     PJ_TURN_TP_UDP = 16,    /**< UDP.	*/
-    PJ_TURN_TP_TCP = 6	    /**< TCP.	*/
-};
+    PJ_TURN_TP_TCP = 6,	    /**< TCP.	*/
+    PJ_TURN_TP_TLS = 256    /**< TLS.	*/
+} pj_turn_tp_type;
+
+
+/** TURN session state */
+typedef enum pj_turn_state_t
+{
+    /**
+     * TURN session has just been created.
+     */
+    PJ_TURN_STATE_NULL,
+
+    /**
+     * TURN server has been configured and now is being resolved via
+     * DNS SRV resolution.
+     */
+    PJ_TURN_STATE_RESOLVING,
+
+    /**
+     * TURN server has been resolved. If there is pending allocation to
+     * be done, it will be invoked immediately.
+     */
+    PJ_TURN_STATE_RESOLVED,
+
+    /**
+     * TURN session has issued ALLOCATE request and is waiting for response
+     * from the TURN server.
+     */
+    PJ_TURN_STATE_ALLOCATING,
+
+    /**
+     * TURN session has successfully allocated relay resoruce and now is
+     * ready to be used.
+     */
+    PJ_TURN_STATE_READY,
+
+    /**
+     * TURN session has issued deallocate request and is waiting for a
+     * response from the TURN server.
+     */
+    PJ_TURN_STATE_DEALLOCATING,
+
+    /**
+     * Deallocate response has been received. Normally the session will
+     * proceed to DESTROYING state immediately.
+     */
+    PJ_TURN_STATE_DEALLOCATED,
+
+    /**
+     * TURN session is being destroyed.
+     */
+    PJ_TURN_STATE_DESTROYING
+
+} pj_turn_state_t;
+
 
 /* ChannelData header */
 typedef struct pj_turn_channel_data
@@ -73,7 +131,9 @@ typedef struct pj_turn_channel_data
 typedef struct pj_turn_session_cb
 {
     /**
-     * Callback to send outgoing packet. This callback is mandatory.
+     * This callback will be called by the TURN session whenever it
+     * needs to send outgoing message. Since the TURN session doesn't
+     * have a socket on its own, this callback must be implemented.
      */
     pj_status_t (*on_send_pkt)(pj_turn_session *sess,
 			       const pj_uint8_t *pkt,
@@ -82,14 +142,21 @@ typedef struct pj_turn_session_cb
 			       unsigned dst_addr_len);
 
     /**
-     * Notification when allocation completes, either successfully or
-     * with failure.
+     * Notification when peer address has been bound successfully to 
+     * a channel number.
+     *
+     * This callback is optional.
      */
-    void (*on_allocate_complete)(pj_turn_session *sess,
-				 pj_status_t status);
+    void (*on_channel_bound)(pj_turn_session *sess,
+			     const pj_sockaddr_t *peer_addr,
+			     unsigned addr_len,
+			     unsigned ch_num);
 
     /**
-     * Notification when data is received.
+     * Notification when incoming data has been received, either through
+     * Data indication or ChannelData message from the TURN server.
+     *
+     * This callback is optional.
      */
     void (*on_rx_data)(pj_turn_session *sess,
 		       const pj_uint8_t *pkt,
@@ -98,9 +165,12 @@ typedef struct pj_turn_session_cb
 		       unsigned addr_len);
 
     /**
-     * Notification when session has been destroyed.
+     * Notification when TURN session state has changed. Application should
+     * implement this callback at least to know that the TURN session is
+     * going to be destroyed.
      */
-    void (*on_destroyed)(pj_turn_session *sess);
+    void (*on_state)(pj_turn_session *sess, pj_turn_state_t old_state,
+		     pj_turn_state_t new_state);
 
 } pj_turn_session_cb;
 
@@ -112,6 +182,7 @@ typedef struct pj_turn_alloc_param
 {
     int	    bandwidth;
     int	    lifetime;
+    int	    ka_interval;
 } pj_turn_alloc_param;
 
 
@@ -120,15 +191,35 @@ typedef struct pj_turn_alloc_param
  */
 typedef struct pj_turn_session_info
 {
+    /**
+     * The relay address
+     */
+    pj_sockaddr	    relay_addr;
+
+    /**
+     * The TURN server address for informational purpose.
+     */
     pj_sockaddr	    server;
+
 } pj_turn_session_info;
 
 
 /**
+ * Get TURN state name.
+ */
+PJ_DECL(const char*) pj_turn_state_name(pj_turn_state_t state);
+
+
+/**
  * Create TURN client session.
  */
 PJ_DECL(pj_status_t) pj_turn_session_create(pj_stun_config *cfg,
+					    const char *name,
+					    int af,
+					    pj_turn_tp_type conn_type,
 					    const pj_turn_session_cb *cb,
+					    void *user_data,
+					    unsigned options,
 					    pj_turn_session **p_sess);
 
 
@@ -139,11 +230,21 @@ PJ_DECL(pj_status_t) pj_turn_session_destroy(pj_turn_session *sess);
 
 
 /**
+ * Re-assign user data.
+ */
+PJ_DECL(pj_status_t) pj_turn_session_set_user_data(pj_turn_session *sess,
+						   void *user_data);
+
+/**
+ * Retrieve user data.
+ */
+PJ_DECL(void*) pj_turn_session_get_user_data(pj_turn_session *sess);
+
+/**
  * Set the server or domain name of the server.
  */
 PJ_DECL(pj_status_t) pj_turn_session_set_server(pj_turn_session *sess,
 					        const pj_str_t *domain,
-					        const pj_str_t *res_name,
 						int default_port,
 						pj_dns_resolver *resolver);
 
diff --git a/pjnath/include/pjnath/turn_udp.h b/pjnath/include/pjnath/turn_udp.h
new file mode 100644
index 00000000..f0d7c3c4
--- /dev/null
+++ b/pjnath/include/pjnath/turn_udp.h
@@ -0,0 +1,134 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2003-2007 Benny Prijono <benny@prijono.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+ */
+#ifndef __PJNATH_TURN_UDP_H__
+#define __PJNATH_TURN_UDP_H__
+
+/**
+ * @file turn_udp.h
+ * @brief TURN relay using UDP client as transport protocol
+ */
+#include <pjnath/turn_session.h>
+
+
+PJ_BEGIN_DECL
+
+
+/* **************************************************************************/
+/**
+ * @defgroup PJNATH_TURN_UDP TURN UDP client
+ * @brief TURN relay using UDP client as transport protocol
+ * @ingroup PJNATH_STUN
+ * @{
+ */
+
+
+/** 
+ * Opaque declaration for TURN UDP client.
+ */
+typedef struct pj_turn_udp pj_turn_udp;
+
+
+typedef struct pj_turn_udp_cb
+{
+    /**
+     * Notification when incoming data has been received, either through
+     * Data indication or ChannelData message from the TURN server.
+     *
+     * This callback is mandatory.
+     */
+    void (*on_rx_data)(pj_turn_udp *udp_rel,
+		       const pj_uint8_t *pkt,
+		       unsigned pkt_len,
+		       const pj_sockaddr_t *peer_addr,
+		       unsigned addr_len);
+
+    /**
+     * Notification when TURN session state has changed. Application should
+     * implement this callback to know that the TURN session is no longer
+     * available.
+     */
+    void (*on_state)(pj_turn_udp *udp_rel, pj_turn_state_t old_state,
+		     pj_turn_state_t new_state);
+
+} pj_turn_udp_cb;
+
+
+/**
+ * Create.
+ */
+PJ_DECL(pj_status_t) pj_turn_udp_create(pj_stun_config *cfg,
+					int af,
+					const pj_turn_udp_cb *cb,
+					unsigned options,
+					void *user_data,
+					pj_turn_udp **p_udp_rel);
+
+/**
+ * Destroy.
+ */
+PJ_DECL(void) pj_turn_udp_destroy(pj_turn_udp *udp_rel);
+
+/**
+ * Set user data.
+ */
+PJ_DECL(pj_status_t) pj_turn_udp_set_user_data(pj_turn_udp *udp_rel,
+					       void *user_data);
+
+/**
+ * Get user data.
+ */
+PJ_DECL(void*) pj_turn_udp_get_user_data(pj_turn_udp *udp_rel);
+
+/**
+ * Initialize.
+ */
+PJ_DECL(pj_status_t) pj_turn_udp_init(pj_turn_udp *udp_rel,
+				      const pj_str_t *domain,
+				      int default_port,
+				      pj_dns_resolver *resolver,
+				      const pj_stun_auth_cred *cred,
+				      const pj_turn_alloc_param *param);
+
+/**
+ * Send packet.
+ */ 
+PJ_DECL(pj_status_t) pj_turn_udp_sendto(pj_turn_udp *udp_rel,
+					const pj_uint8_t *pkt,
+					unsigned pkt_len,
+					const pj_sockaddr_t *addr,
+					unsigned addr_len);
+
+/**
+ * Bind a peer address to a channel number.
+ */
+PJ_DECL(pj_status_t) pj_turn_udp_bind_channel(pj_turn_udp *udp_rel,
+					      const pj_sockaddr_t *peer,
+					      unsigned addr_len);
+
+
+/**
+ * @}
+ */
+
+
+PJ_END_DECL
+
+
+#endif	/* __PJNATH_TURN_UDP_H__ */
+