Index: pjproject/trunk/pjnath/include/pjnath/stun_session.h
===================================================================
--- pjproject/trunk/pjnath/include/pjnath/stun_session.h	(revision 1877)
+++ pjproject/trunk/pjnath/include/pjnath/stun_session.h	(revision 1913)
@@ -65,4 +65,13 @@
      *
      * @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.
@@ -74,4 +83,5 @@
      */
     pj_status_t (*on_send_msg)(pj_stun_session *sess,
+			       void *token,
 			       const void *pkt,
 			       pj_size_t pkt_size,
@@ -80,5 +90,8 @@
 
     /** 
-     * 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
@@ -90,4 +103,6 @@
      * @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.
@@ -101,4 +116,5 @@
 				 unsigned pkt_len,
 				 const pj_stun_rx_data *rdata,
+				 void *token,
 				 const pj_sockaddr_t *src_addr,
 				 unsigned src_addr_len);
@@ -106,5 +122,9 @@
     /**
      * 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.
@@ -116,4 +136,8 @@
      *			    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,
@@ -128,4 +152,5 @@
     void (*on_request_complete)(pj_stun_session *sess,
 			        pj_status_t status,
+				void *token,
 			        pj_stun_tx_data *tdata,
 			        const pj_stun_msg *response,
@@ -135,5 +160,21 @@
 
     /**
-     * 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,
@@ -141,4 +182,5 @@
 				    unsigned pkt_len,
 				    const pj_stun_msg *msg,
+				    void *token,
 				    const pj_sockaddr_t *src_addr,
 				    unsigned src_addr_len);
@@ -178,7 +220,8 @@
     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.	    */
@@ -369,5 +412,19 @@
  *
  * @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.
@@ -378,5 +435,7 @@
  */
 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,
@@ -384,5 +443,8 @@
 
 /**
- * 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.
@@ -396,4 +458,10 @@
  *		    \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
@@ -410,4 +478,5 @@
 					     unsigned code, 
 					     const char *err_msg,
+					     void *token,
 					     pj_bool_t cache, 
 					     const pj_sockaddr_t *dst_addr, 
@@ -469,5 +538,12 @@
  *			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.
  *
@@ -478,4 +554,5 @@
 					       pj_size_t pkt_size,
 					       unsigned options,
+					       void *token,
 					       unsigned *parsed_len,
 					       const pj_sockaddr_t *src_addr,
