Index: pjproject/trunk/pjlib-util/src/pjstun-client/stun_session.h
===================================================================
--- pjproject/trunk/pjlib-util/src/pjstun-client/stun_session.h	(revision 993)
+++ pjproject/trunk/pjlib-util/src/pjstun-client/stun_session.h	(revision 996)
@@ -26,34 +26,167 @@
 
 
+/** Forward declaration for pj_stun_tx_data */
 typedef struct pj_stun_tx_data pj_stun_tx_data;
+
+/** Forward declaration for pj_stun_session */
 typedef struct pj_stun_session pj_stun_session;
 
+/**
+ * This is the callback to be registered to pj_stun_session, to send
+ * outgoing message and to receive various notifications from the STUN
+ * session.
+ */
 typedef struct pj_stun_session_cb
 {
+    /**
+     * Callback to be called by the STUN session to send outgoing message.
+     *
+     * @param tdata	    The STUN transmit data containing the original
+     *			    STUN message
+     * @param pkt	    Packet to be sent.
+     * @param pkt_size	    Size of the packet to be sent.
+     * @param addr_len	    Length of destination address.
+     * @param dst_addr	    The destination address.
+     *
+     * @return		    The callback should return the status of the
+     *			    packet sending.
+     */
     pj_status_t (*on_send_msg)(pj_stun_tx_data *tdata,
+			       const void *pkt,
+			       pj_size_t pkt_size,
 			       unsigned addr_len, 
 			       const pj_sockaddr_t *dst_addr);
 
-    void (*on_bind_response)(void *user_data, pj_status_t status, pj_stun_msg *response);
-    void (*on_allocate_response)(void *user_data, pj_status_t status, pj_stun_msg *response);
-    void (*on_set_active_destination_response)(void *user_data, pj_status_t status, pj_stun_msg *response);
-    void (*on_connect_response)(void *user_data, pj_status_t status, pj_stun_msg *response);
+    /**
+     * Callback to be called when Binding response is received or the 
+     * transaction has timed out.
+     *
+     * @param sess	    The STUN session.
+     * @param status	    Status of the request. If the value if not
+     *			    PJ_SUCCESS, the transaction has timed-out
+     *			    or other error has occurred, and the response
+     *			    argument may be NULL.
+     * @param request	    The original STUN request.
+     * @param response	    The response message, on successful transaction.
+     */
+    void (*on_bind_response)(pj_stun_session *sess, 
+			     pj_status_t status, 
+			     pj_stun_tx_data *request,
+			     const pj_stun_msg *response);
+
+    /**
+     * Callback to be called when Allocate response is received or the 
+     * transaction has timed out.
+     *
+     * @param sess	    The STUN session.
+     * @param status	    Status of the request. If the value if not
+     *			    PJ_SUCCESS, the transaction has timed-out
+     *			    or other error has occurred, and the response
+     *			    argument may be NULL.
+     * @param request	    The original STUN request.
+     * @param response	    The response message, on successful transaction.
+     */
+    void (*on_allocate_response)(pj_stun_session *sess, 
+				 pj_status_t status, 
+				 pj_stun_tx_data *request,
+				 const pj_stun_msg *response);
+
+    /**
+     * Callback to be called when Set Active Destination response is received
+     * or the transaction has timed out.
+     *
+     * @param sess	    The STUN session.
+     * @param status	    Status of the request. If the value if not
+     *			    PJ_SUCCESS, the transaction has timed-out
+     *			    or other error has occurred, and the response
+     *			    argument may be NULL.
+     * @param request	    The original STUN request.
+     * @param response	    The response message, on successful transaction.
+     */
+    void (*on_set_active_destination_response)(pj_stun_session *sess, 
+					       pj_status_t status, 
+					       pj_stun_tx_data *request,
+					       const pj_stun_msg *response);
+
+    /**
+     * Callback to be called when Connect response is received or the 
+     * transaction has timed out.
+     *
+     * @param sess	    The STUN session.
+     * @param status	    Status of the request. If the value if not
+     *			    PJ_SUCCESS, the transaction has timed-out
+     *			    or other error has occurred, and the response
+     *			    argument may be NULL.
+     * @param request	    The original STUN request.
+     * @param response	    The response message, on successful transaction.
+     */
+    void (*on_connect_response)( pj_stun_session *sess, 
+				 pj_status_t status, 
+				 pj_stun_tx_data *request,
+				 const pj_stun_msg *response);
 } pj_stun_session_cb;
 
 
+/**
+ * This structure describe the outgoing STUN transmit data to carry the
+ * message to be sent.
+ */
 struct pj_stun_tx_data
 {
     PJ_DECL_LIST_MEMBER(struct pj_stun_tx_data);
 
-    pj_pool_t		*pool;
-    pj_stun_session	*sess;
-    pj_stun_msg		*msg;
-    void		*user_data;
-
-    pj_stun_client_tsx	*client_tsx;
-    pj_uint8_t		 client_key[12];
+    pj_pool_t		*pool;		/**< Pool.			    */
+    pj_stun_session	*sess;		/**< The STUN session.		    */
+    pj_stun_msg		*msg;		/**< The STUN message.		    */
+    void		*user_data;	/**< Arbitrary user data.	    */
+
+    pj_stun_client_tsx	*client_tsx;	/**< Client STUN transaction.	    */
+    pj_uint8_t		 client_key[12];/**< Client transaction key.	    */
+
+    void		*pkt;		/**< The STUN packet.		    */
+    unsigned		 max_len;	/**< Length of packet buffer.	    */
+    unsigned		 pkt_size;	/**< The actual length of STUN pkt. */
+
+    unsigned		 addr_len;	/**< Length of destination address. */
+    const pj_sockaddr_t	*dst_addr;	/**< Destination address.	    */
 };
 
 
+/**
+ * Options that can be specified when creating or sending outgoing STUN
+ * messages. These options may be specified as bitmask.
+ */
+enum pj_stun_session_option
+{
+    /**
+     * Add short term credential to the message. This option may not be used
+     * together with PJ_STUN_USE_LONG_TERM_CRED option.
+     */
+    PJ_STUN_USE_SHORT_TERM_CRED	= 1,
+
+    /**
+     * Add long term credential to the message. This option may not be used
+     * together with PJ_STUN_USE_SHORT_TERM_CRED option.
+     */
+    PJ_STUN_USE_LONG_TERM_CRED	= 2,
+
+    /**
+     * Add STUN fingerprint to the message.
+     */
+    PJ_STUN_USE_FINGERPRINT	= 4
+};
+
+
+/**
+ * Create a STUN session.
+ *
+ * @param endpt	    The STUN endpoint, to be used to register timers etc.
+ * @param name	    Optional name to be associated with this instance. The
+ *		    name will be used for example for logging purpose.
+ * @param cb	    Session callback.
+ * @param p_sess    Pointer to receive STUN session instance.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_create(pj_stun_endpoint *endpt,
 					    const char *name,
@@ -61,47 +194,219 @@
 					    pj_stun_session **p_sess);
 
+/**
+ * Destroy the STUN session.
+ *
+ * @param sess	    The STUN session instance.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_destroy(pj_stun_session *sess);
 
+/**
+ * Associated an arbitrary data with this STUN session. The user data may
+ * be retrieved later with pj_stun_session_get_user_data() function.
+ *
+ * @param sess	    The STUN session instance.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_set_user_data(pj_stun_session *sess,
 						   void *user_data);
 
+/**
+ * Retrieve the user data previously associated to this STUN session with
+ * pj_stun_session_set_user_data().
+ *
+ * @param sess	    The STUN session instance.
+ *
+ * @return	    The user data associated with this STUN session.
+ */
 PJ_DECL(void*) pj_stun_session_get_user_data(pj_stun_session *sess);
 
-PJ_DECL(pj_status_t) pj_stun_session_set_credential(pj_stun_session *sess,
-						    const pj_str_t *realm,
-						    const pj_str_t *user,
-						    const pj_str_t *passwd);
-
-PJ_DECL(pj_status_t) pj_stun_session_enable_fingerprint(pj_stun_session *sess,
-							pj_bool_t enabled);
-
+/**
+ * Save a long term credential to be used by this STUN session when sending
+ * outgoing messages. After long term credential is configured, application
+ * may specify PJ_STUN_USE_LONG_TERM_CRED option when sending outgoing STUN
+ * message to send the long term credential in the message.
+ *
+ * @param sess	    The STUN session instance.
+ * @param realm	    Realm of the long term credential.
+ * @param user	    The user name.
+ * @param passwd    The pain-text password.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) 
+pj_stun_session_set_long_term_credential(pj_stun_session *sess,
+					 const pj_str_t *realm,
+					 const pj_str_t *user,
+					 const pj_str_t *passwd);
+
+
+/**
+ * Save a short term credential to be used by this STUN session when sending
+ * outgoing messages. After short term credential is configured, application
+ * may specify PJ_STUN_USE_SHORT_TERM_CRED option when sending outgoing STUN
+ * message to send the short term credential in the message.
+ *
+ * @param sess	    The STUN session instance.
+ * @param user	    The user name.
+ * @param passwd    The pain-text password.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) 
+pj_stun_session_set_short_term_credential(pj_stun_session *sess,
+					  const pj_str_t *user,
+					  const pj_str_t *passwd);
+
+/**
+ * Create a STUN Bind request message. After the message has been 
+ * successfully created, application can send the message by calling 
+ * pj_stun_session_send_msg().
+ *
+ * @param sess	    The STUN session instance.
+ * @param p_tdata   Pointer to receive STUN transmit data instance containing
+ *		    the request.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_create_bind_req(pj_stun_session *sess,
 						     pj_stun_tx_data **p_tdata);
 
+/**
+ * Create a STUN Allocate request message. After the message has been
+ * successfully created, application can send the message by calling  
+ * pj_stun_session_send_msg().
+ *
+ * @param sess	    The STUN session instance.
+ * @param p_tdata   Pointer to receive STUN transmit data instance containing
+ *		    the request.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_create_allocate_req(pj_stun_session *sess,
 							 pj_stun_tx_data **p_tdata);
 
+/**
+ * Create a STUN Set Active Destination request message. After the message 
+ * has been successfully created, application can send the message by calling
+ * pj_stun_session_send_msg().
+ *
+ * @param sess	    The STUN session instance.
+ * @param p_tdata   Pointer to receive STUN transmit data instance containing
+ *		    the request.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) 
 pj_stun_session_create_set_active_destination_req(pj_stun_session *sess,
 						  pj_stun_tx_data **p_tdata);
 
+/**
+ * Create a STUN Connect request message. After the message has been 
+ * successfully created, application can send the message by calling 
+ * pj_stun_session_send_msg().
+ *
+ * @param sess	    The STUN session instance.
+ * @param p_tdata   Pointer to receive STUN transmit data instance containing
+ *		    the request.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_create_connect_req(pj_stun_session *sess,
 							pj_stun_tx_data **p_tdata);
 
-PJ_DECL(pj_status_t) 
+/**
+ * Create a STUN Connection Status Indication message. After the message 
+ * has been successfully created, application can send the message by calling
+ * pj_stun_session_send_msg().
+ *
+ * @param sess	    The STUN session instance.
+ * @param p_tdata   Pointer to receive STUN transmit data instance containing
+ *		    the message.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t)
 pj_stun_session_create_connection_status_ind(pj_stun_session *sess,
 					     pj_stun_tx_data **p_tdata);
 
+/**
+ * Create a STUN Send Indication message. After the message has been 
+ * successfully created, application can send the message by calling 
+ * pj_stun_session_send_msg().
+ *
+ * @param sess	    The STUN session instance.
+ * @param p_tdata   Pointer to receive STUN transmit data instance containing
+ *		    the message.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_create_send_ind(pj_stun_session *sess,
 						     pj_stun_tx_data **p_tdata);
 
+/**
+ * Create a STUN Data Indication message. After the message has been 
+ * successfully created, application can send the message by calling 
+ * pj_stun_session_send_msg().
+ *
+ * @param sess	    The STUN session instance.
+ * @param p_tdata   Pointer to receive STUN transmit data instance containing
+ *		    the message.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_create_data_ind(pj_stun_session *sess,
 						     pj_stun_tx_data **p_tdata);
 
+/**
+ * Send STUN message to the specified destination. This function will encode
+ * the pj_stun_msg instance to a packet buffer, and add credential or
+ * fingerprint if necessary. If the message is a request, the session will
+ * also create and manage a STUN client transaction to be used to manage the
+ * retransmission of the request. After the message has been encoded and
+ * transaction is setup, the \a on_send_msg() callback of pj_stun_session_cb
+ * (which is registered when the STUN session is created) will be called
+ * to actually send the message to the wire.
+ *
+ * @param sess	    The STUN session instance.
+ * @param options   Optional flags, from pj_stun_session_option.
+ * @param addr_len  Length of destination address.
+ * @param dst_addr  The destination socket address.
+ * @param tdata	    The STUN transmit data containing the STUN message to
+ *		    be sent.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess,
+					      unsigned options,
 					      unsigned addr_len,
-					      const pj_sockaddr_t *server,
+					      const pj_sockaddr_t *dst_addr,
 					      pj_stun_tx_data *tdata);
 
+/**
+ * Application must call this function to notify the STUN session about
+ * the arrival of STUN packet. The STUN packet MUST have been checked
+ * first with #pj_stun_msg_check() to verify that this is indeed a valid
+ * STUN packet.
+ *
+ * The STUN session will decode the packet into pj_stun_msg, and process
+ * the message accordingly. If the message is a response, it will search
+ * through the outstanding STUN client transactions for a matching
+ * transaction ID and hand over the response to the transaction.
+ *
+ * On successful message processing, application will be notified about
+ * the message via one of the pj_stun_session_cb callback.
+ *
+ * @param sess	     The STUN session instance.
+ * @param packet     The packet containing STUN message.
+ * @param pkt_size   Size of the packet.
+ * @param parsed_len Optional pointer to receive the size of the parsed
+ *		     STUN message (useful if packet is received via a
+ *		     stream oriented protocol).
+ *
+ * @return	     PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess,
 					       const void *packet,
