More ticket #485: huge changeset to support TURN TCP. Please see ticket #485 for the details

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

4 files changed, 156 insertions, 43 deletions

diff --git a/pjnath/include/pjnath.h b/pjnath/include/pjnath.h
index f8e4d73d..962aeba0 100644
--- a/pjnath/include/pjnath.h
+++ b/pjnath/include/pjnath.h
@@ -28,6 +28,6 @@
 #include <pjnath/stun_session.h>
 #include <pjnath/stun_transaction.h>
 #include <pjnath/turn_session.h>
-#include <pjnath/turn_udp.h>
+#include <pjnath/turn_sock.h>
 #include <pjnath/types.h>
 
diff --git a/pjnath/include/pjnath/stun_session.h b/pjnath/include/pjnath/stun_session.h
index 187064ed..821e765b 100644
--- a/pjnath/include/pjnath/stun_session.h
+++ b/pjnath/include/pjnath/stun_session.h
@@ -64,6 +64,15 @@ typedef struct pj_stun_session_cb
      * Callback to be called by the STUN session to send outgoing message.
      *
      * @param sess	    The STUN session.
+     * @param token	    The token associated with this outgoing message
+     *			    and was set by the application. This token was 
+     *			    set by application in pj_stun_session_send_msg()
+     *			    for outgoing messages that are initiated by the
+     *			    application, or in pj_stun_session_on_rx_pkt()
+     *			    if this message is a response that was internally
+     *			    generated by the STUN session (for example, an
+     *			    401/Unauthorized response). Application may use
+     *			    this facility for any purposes.
      * @param pkt	    Packet to be sent.
      * @param pkt_size	    Size of the packet to be sent.
      * @param dst_addr	    The destination address.
@@ -73,13 +82,17 @@ typedef struct pj_stun_session_cb
      *			    packet sending.
      */
     pj_status_t (*on_send_msg)(pj_stun_session *sess,
+			       void *token,
 			       const void *pkt,
 			       pj_size_t pkt_size,
 			       const pj_sockaddr_t *dst_addr,
 			       unsigned addr_len);
 
     /** 
-     * Callback to be called on incoming STUN request message. In the 
+     * Callback to be called on incoming STUN request message. This function
+     * is called when application calls pj_stun_session_on_rx_pkt() and when
+     * the STUN session has detected that the incoming STUN message is a
+     * STUN request message. In the 
      * callback processing, application MUST create a response by calling
      * pj_stun_session_create_response() function and send the response
      * with pj_stun_session_send_msg() function, before returning from
@@ -89,6 +102,8 @@ typedef struct pj_stun_session_cb
      * @param pkt	    Pointer to the original STUN packet.
      * @param pkt_len	    Length of the STUN packet.
      * @param rdata	    Data containing incoming request message.
+     * @param token	    The token that was set by the application when
+     *			    calling pj_stun_session_on_rx_pkt() function.
      * @param src_addr	    Source address of the packet.
      * @param src_addr_len  Length of the source address.
      *
@@ -100,12 +115,17 @@ typedef struct pj_stun_session_cb
 				 const pj_uint8_t *pkt,
 				 unsigned pkt_len,
 				 const pj_stun_rx_data *rdata,
+				 void *token,
 				 const pj_sockaddr_t *src_addr,
 				 unsigned src_addr_len);
 
     /**
      * Callback to be called when response is received or the transaction 
-     * has timed out.
+     * has timed out. This callback is called either when application calls
+     * pj_stun_session_on_rx_pkt() with the packet containing a STUN
+     * response for the client transaction, or when the internal timer of
+     * the STUN client transaction has timed-out before a STUN response is
+     * received.
      *
      * @param sess	    The STUN session.
      * @param status	    Status of the request. If the value if not
@@ -115,6 +135,10 @@ 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 token	    The token that was set by the application  when
+     *			    calling pj_stun_session_send_msg() function.
+     *			    Please not that this token IS NOT the token
+     *			    that was given in pj_stun_session_on_rx_pkt().
      * @param tdata	    The original STUN request.
      * @param response	    The response message, on successful transaction,
      *			    or otherwise MAY BE NULL if status is not success.
@@ -127,6 +151,7 @@ typedef struct pj_stun_session_cb
      */
     void (*on_request_complete)(pj_stun_session *sess,
 			        pj_status_t status,
+				void *token,
 			        pj_stun_tx_data *tdata,
 			        const pj_stun_msg *response,
 				const pj_sockaddr_t *src_addr,
@@ -134,12 +159,29 @@ typedef struct pj_stun_session_cb
 
 
     /**
-     * Type of callback to be called on incoming STUN indication.
+     * Callback to be called on incoming STUN request message. This function
+     * is called when application calls pj_stun_session_on_rx_pkt() and when
+     * the STUN session has detected that the incoming STUN message is a
+     * STUN indication message.
+     *
+     * @param sess	    The STUN session.
+     * @param pkt	    Pointer to the original STUN packet.
+     * @param pkt_len	    Length of the STUN packet.
+     * @param msg	    The parsed STUN indication.
+     * @param token	    The token that was set by the application when
+     *			    calling pj_stun_session_on_rx_pkt() function.
+     * @param src_addr	    Source address of the packet.
+     * @param src_addr_len  Length of the source address.
+     *
+     * @return		    The return value of this callback will be
+     *			    returned back to pj_stun_session_on_rx_pkt()
+     *			    function.
      */
     pj_status_t (*on_rx_indication)(pj_stun_session *sess,
 				    const pj_uint8_t *pkt,
 				    unsigned pkt_len,
 				    const pj_stun_msg *msg,
+				    void *token,
 				    const pj_sockaddr_t *src_addr,
 				    unsigned src_addr_len);
 
@@ -177,9 +219,10 @@ struct pj_stun_tx_data
     pj_stun_session	*sess;		/**< The STUN session.		    */
     pj_stun_msg		*msg;		/**< The STUN message.		    */
 
-    void		*user_data;	/**< Arbitrary application data.    */
+    void		*token;		/**< The token.			    */
 
     pj_stun_client_tsx	*client_tsx;	/**< Client STUN transaction.	    */
+    pj_bool_t		 retransmit;	/**< Retransmit request?	    */
     pj_uint32_t		 msg_magic;	/**< Message magic.		    */
     pj_uint8_t		 msg_key[12];	/**< Message/transaction key.	    */
 
@@ -368,7 +411,21 @@ PJ_DECL(pj_status_t) pj_stun_session_create_res(pj_stun_session *sess,
  * to actually send the message to the wire.
  *
  * @param sess	    The STUN session instance.
- * @param cache_res If PJ_TRUE then response will be cached.
+ * @param token	    Optional token which will be given back to application in
+ *		    \a on_send_msg() callback and \a on_request_complete()
+ *		    callback, if the message is a STUN request message. 
+ *		    Internally this function will put the token in the 
+ *		    \a token field of pj_stun_tx_data, hence it will
+ *		    overwrite any value that the application puts there.
+ * @param cache_res If the message is a response message for an incoming
+ *		    request, specify PJ_TRUE to instruct the STUN session
+ *		    to cache this response for subsequent incoming request
+ *		    retransmission. Otherwise this parameter will be ignored
+ *		    for non-response message.
+ * @param retransmit If the message is a request message, specify whether the
+ *		    request should be retransmitted. Normally application will
+ *		    specify TRUE if the underlying transport is UDP and FALSE
+ *		    if the underlying transport is TCP or TLS.
  * @param dst_addr  The destination socket address.
  * @param addr_len  Length of destination address.
  * @param tdata	    The STUN transmit data containing the STUN message to
@@ -377,13 +434,18 @@ PJ_DECL(pj_status_t) pj_stun_session_create_res(pj_stun_session *sess,
  * @return	    PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess,
+					      void *token,
 					      pj_bool_t cache_res,
+					      pj_bool_t retransmit,
 					      const pj_sockaddr_t *dst_addr,
 					      unsigned addr_len,
 					      pj_stun_tx_data *tdata);
 
 /**
- * Create and send STUN response message.
+ * This is a utility function to create and send response for an incoming
+ * STUN request. Internally this function calls pj_stun_session_create_res()
+ * and pj_stun_session_send_msg(). It is provided here as a matter of
+ * convenience.
  *
  * @param sess	    The STUN session instance.
  * @param rdata	    The STUN request message to be responded.
@@ -395,6 +457,12 @@ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess,
  *		    creating error response. If the value is NULL and the
  *		    \a err_code is non-zero, then default error message will
  *		    be used.
+ * @param token	    Optional token which will be given back to application in
+ *		    \a on_send_msg() callback and \a on_request_complete()
+ *		    callback, if the message is a STUN request message. 
+ *		    Internally this function will put the token in the 
+ *		    \a token field of pj_stun_tx_data, hence it will
+ *		    overwrite any value that the application puts there.
  * @param cache	    Specify whether session should cache this response for
  *		    future request retransmission. If TRUE, subsequent request
  *		    retransmission will be handled by the session and it 
@@ -409,6 +477,7 @@ PJ_DECL(pj_status_t) pj_stun_session_respond(pj_stun_session *sess,
 					     const pj_stun_rx_data *rdata,
 					     unsigned code, 
 					     const char *err_msg,
+					     void *token,
 					     pj_bool_t cache, 
 					     const pj_sockaddr_t *dst_addr, 
 					     unsigned addr_len);
@@ -468,7 +537,14 @@ PJ_DECL(pj_status_t) pj_stun_session_retransmit_req(pj_stun_session *sess,
  * @param parsed_len	Optional pointer to receive the size of the parsed
  *			STUN message (useful if packet is received via a
  *			stream oriented protocol).
- * @param src_addr	The source address of the packet.
+ * @param token		Optional token which will be given back to application
+ *			in the \a on_rx_request(), \a on_rx_indication() and 
+ *			\a on_send_msg() callbacks. The token can be used to 
+ *			associate processing or incoming request or indication
+ *			with some context.
+ * @param src_addr	The source address of the packet, which will also
+ *			be given back to application callbacks, along with
+ *			source address length.
  * @param src_addr_len	Length of the source address.
  *
  * @return		PJ_SUCCESS on success, or the appropriate error code.
@@ -477,6 +553,7 @@ PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess,
 					       const void *packet,
 					       pj_size_t pkt_size,
 					       unsigned options,
+					       void *token,
 					       unsigned *parsed_len,
 					       const pj_sockaddr_t *src_addr,
 					       unsigned src_addr_len);
diff --git a/pjnath/include/pjnath/turn_session.h b/pjnath/include/pjnath/turn_session.h
index 8a93414a..0c0f3cef 100644
--- a/pjnath/include/pjnath/turn_session.h
+++ b/pjnath/include/pjnath/turn_session.h
@@ -55,12 +55,29 @@ typedef struct pj_turn_session pj_turn_session;
 #define PJ_TURN_PEER_HTABLE_SIZE    8
 
 
-/** TURN transport types */
+/** 
+ * TURN transport types, which will be used both to specify the connection 
+ * type for reaching TURN server and the type of allocation transport to be 
+ * requested to server (the REQUESTED-TRANSPORT attribute).
+ */
 typedef enum pj_turn_tp_type
 {
-    PJ_TURN_TP_UDP = 17,    /**< UDP.	*/
-    PJ_TURN_TP_TCP = 6,	    /**< TCP.	*/
-    PJ_TURN_TP_TLS = 256    /**< TLS.	*/
+    /**
+     * UDP transport, which value corresponds to IANA protocol number.
+     */
+    PJ_TURN_TP_UDP = 17,
+
+    /**
+     * TCP transport, which value corresponds to IANA protocol number.
+     */
+    PJ_TURN_TP_TCP = 6,
+
+    /**
+     * TLS transport. The TLS transport will only be used as the connection
+     * type to reach the server and never as the allocation transport type.
+     */
+    PJ_TURN_TP_TLS = 255
+
 } pj_turn_tp_type;
 
 
@@ -220,6 +237,18 @@ typedef struct pj_turn_session_info
 
 
 /**
+ * Create default pj_turn_alloc_param.
+ */
+PJ_DECL(void) pj_turn_alloc_param_default(pj_turn_alloc_param *prm);
+
+/**
+ * Duplicate pj_turn_alloc_param.
+ */
+PJ_DECL(void) pj_turn_alloc_param_copy(pj_pool_t *pool, 
+				       pj_turn_alloc_param *dst,
+				       const pj_turn_alloc_param *src);
+
+/**
  * Get TURN state name.
  */
 PJ_DECL(const char*) pj_turn_state_name(pj_turn_state_t state);
@@ -239,7 +268,13 @@ PJ_DECL(pj_status_t) pj_turn_session_create(pj_stun_config *cfg,
 
 
 /**
- * Destroy TURN client session.
+ * Shutdown TURN client session.
+ */
+PJ_DECL(pj_status_t) pj_turn_session_shutdown(pj_turn_session *sess);
+
+
+/**
+ * Forcefully destroy the TURN session.
  */
 PJ_DECL(pj_status_t) pj_turn_session_destroy(pj_turn_session *sess);
 
diff --git a/pjnath/include/pjnath/turn_udp.h b/pjnath/include/pjnath/turn_sock.h
index 2c701590..91bf9e20 100644
--- a/pjnath/include/pjnath/turn_udp.h
+++ b/pjnath/include/pjnath/turn_sock.h
@@ -16,11 +16,11 @@
  * 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__
+#ifndef __PJNATH_turn_sock_H__
+#define __PJNATH_turn_sock_H__
 
 /**
- * @file turn_udp.h
+ * @file turn_sock.h
  * @brief TURN relay using UDP client as transport protocol
  */
 #include <pjnath/turn_session.h>
@@ -31,20 +31,20 @@ PJ_BEGIN_DECL
 
 /* **************************************************************************/
 /**
- * @defgroup PJNATH_TURN_UDP TURN UDP client
- * @brief TURN relay using UDP client as transport protocol
+ * @defgroup PJNATH_TURN_UDP TURN TCP client
+ * @brief TURN relay using TCP client as transport protocol
  * @ingroup PJNATH_STUN
  * @{
  */
 
 
 /** 
- * Opaque declaration for TURN UDP client.
+ * Opaque declaration for TURN TCP client.
  */
-typedef struct pj_turn_udp pj_turn_udp;
+typedef struct pj_turn_sock pj_turn_sock;
 
 
-typedef struct pj_turn_udp_cb
+typedef struct pj_turn_sock_cb
 {
     /**
      * Notification when incoming data has been received, either through
@@ -52,7 +52,7 @@ typedef struct pj_turn_udp_cb
      *
      * This callback is mandatory.
      */
-    void (*on_rx_data)(pj_turn_udp *udp_rel,
+    void (*on_rx_data)(pj_turn_sock *turn_sock,
 		       const pj_uint8_t *pkt,
 		       unsigned pkt_len,
 		       const pj_sockaddr_t *peer_addr,
@@ -63,59 +63,60 @@ typedef struct pj_turn_udp_cb
      * 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,
+    void (*on_state)(pj_turn_sock *turn_sock, pj_turn_state_t old_state,
 		     pj_turn_state_t new_state);
 
-} pj_turn_udp_cb;
+} pj_turn_sock_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);
+PJ_DECL(pj_status_t) pj_turn_sock_create(pj_stun_config *cfg,
+					 int af,
+					 pj_turn_tp_type conn_type,
+					 const pj_turn_sock_cb *cb,
+					 unsigned options,
+					 void *user_data,
+					 pj_turn_sock **p_turn_sock);
 
 /**
  * Destroy.
  */
-PJ_DECL(void) pj_turn_udp_destroy(pj_turn_udp *udp_rel);
+PJ_DECL(void) pj_turn_sock_destroy(pj_turn_sock *turn_sock);
 
 /**
  * Set user data.
  */
-PJ_DECL(pj_status_t) pj_turn_udp_set_user_data(pj_turn_udp *udp_rel,
+PJ_DECL(pj_status_t) pj_turn_sock_set_user_data(pj_turn_sock *turn_sock,
 					       void *user_data);
 
 /**
  * Get user data.
  */
-PJ_DECL(void*) pj_turn_udp_get_user_data(pj_turn_udp *udp_rel);
+PJ_DECL(void*) pj_turn_sock_get_user_data(pj_turn_sock *turn_sock);
 
 
 /**
  * Get info.
  */
-PJ_DECL(pj_status_t) pj_turn_udp_get_info(pj_turn_udp *udp_rel,
+PJ_DECL(pj_status_t) pj_turn_sock_get_info(pj_turn_sock *turn_sock,
 					  pj_turn_session_info *info);
 
 /**
  * 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);
+PJ_DECL(pj_status_t) pj_turn_sock_init(pj_turn_sock *turn_sock,
+				       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,
+PJ_DECL(pj_status_t) pj_turn_sock_sendto(pj_turn_sock *turn_sock,
 					const pj_uint8_t *pkt,
 					unsigned pkt_len,
 					const pj_sockaddr_t *addr,
@@ -124,7 +125,7 @@ PJ_DECL(pj_status_t) pj_turn_udp_sendto(pj_turn_udp *udp_rel,
 /**
  * Bind a peer address to a channel number.
  */
-PJ_DECL(pj_status_t) pj_turn_udp_bind_channel(pj_turn_udp *udp_rel,
+PJ_DECL(pj_status_t) pj_turn_sock_bind_channel(pj_turn_sock *turn_sock,
 					      const pj_sockaddr_t *peer,
 					      unsigned addr_len);
 
@@ -137,5 +138,5 @@ PJ_DECL(pj_status_t) pj_turn_udp_bind_channel(pj_turn_udp *udp_rel,
 PJ_END_DECL
 
 
-#endif	/* __PJNATH_TURN_UDP_H__ */
+#endif	/* __PJNATH_turn_sock_H__ */