Related to ticket #399: added comments etc.

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

2 files changed, 101 insertions, 7 deletions

diff --git a/pjnath/include/pjnath/nat_detect.h b/pjnath/include/pjnath/nat_detect.h
index 014a8911..e79ffb14 100644
--- a/pjnath/include/pjnath/nat_detect.h
+++ b/pjnath/include/pjnath/nat_detect.h
@@ -34,23 +34,81 @@ PJ_BEGIN_DECL
  * @brief NAT Classification/Detection Tool
  * @ingroup PJNATH_ICE
  * @{
+ *
  * This module provides one function to perform NAT classification and
- * detection.
+ * detection. NAT type detection is performed by calling
+ * #pj_stun_detect_nat_type() function.
  */
 
+
 /**
- * This enumeration describes the NAT types.
+ * This enumeration describes the NAT types, as specified by RFC 3489
+ * Section 5, NAT Variations.
  */
 typedef enum pj_stun_nat_type
 {
+    /**
+     * NAT type is unknown, because the detection has failed.
+     */
     PJ_STUN_NAT_TYPE_UNKNOWN,
+
+    /**
+     * This specifies that the client has open access to Internet (or
+     * at least, its behind a firewall that behaves like a full-cone NAT,
+     * but without the translation)
+     */
     PJ_STUN_NAT_TYPE_OPEN,
+
+    /**
+     * This specifies that communication with server has failed, probably
+     * because UDP packets are blocked.
+     */
     PJ_STUN_NAT_TYPE_BLOCKED,
+
+    /**
+     * Firewall that allows UDP out, and responses have to come back to
+     * the source of the request (like a symmetric NAT, but no
+     * translation.
+     */
     PJ_STUN_NAT_TYPE_SYMMETRIC_UDP,
+
+    /**
+     * A full cone NAT is one where all requests from the same internal 
+     * IP address and port are mapped to the same external IP address and
+     * port.  Furthermore, any external host can send a packet to the 
+     * internal host, by sending a packet to the mapped external address.
+     */
     PJ_STUN_NAT_TYPE_FULL_CONE,
+
+    /**
+     * A symmetric NAT is one where all requests from the same internal 
+     * IP address and port, to a specific destination IP address and port,
+     * are mapped to the same external IP address and port.  If the same 
+     * host sends a packet with the same source address and port, but to 
+     * a different destination, a different mapping is used.  Furthermore,
+     * only the external host that receives a packet can send a UDP packet
+     * back to the internal host.
+     */
     PJ_STUN_NAT_TYPE_SYMMETRIC,
+
+    /**
+     * A restricted cone NAT is one where all requests from the same 
+     * internal IP address and port are mapped to the same external IP 
+     * address and port.  Unlike a full cone NAT, an external host (with 
+     * IP address X) can send a packet to the internal host only if the 
+     * internal host had previously sent a packet to IP address X.
+     */
     PJ_STUN_NAT_TYPE_RESTRICTED,
+
+    /**
+     * A port restricted cone NAT is like a restricted cone NAT, but the 
+     * restriction includes port numbers. Specifically, an external host 
+     * can send a packet, with source IP address X and source port P, 
+     * to the internal host only if the internal host had previously sent
+     * a packet to IP address X and port P.
+     */
     PJ_STUN_NAT_TYPE_PORT_RESTRICTED
+
 } pj_stun_nat_type;
 
 
@@ -59,10 +117,29 @@ typedef enum pj_stun_nat_type
  */
 typedef struct pj_stun_nat_detect_result
 {
+    /**
+     * Status of the detection process. If this value is not PJ_SUCCESS,
+     * the detection has failed and \a nat_type field will contain
+     * PJ_STUN_NAT_TYPE_UNKNOWN.
+     */
     pj_status_t		 status;
+
+    /**
+     * The text describing the status, if the status is not PJ_SUCCESS.
+     */
     const char		*status_text;
+
+    /**
+     * This contains the NAT type as detected by the detection procedure.
+     * This value is only valid when the \a status is PJ_SUCCESS.
+     */
     pj_stun_nat_type	 nat_type;
+
+    /**
+     * Text describing that NAT type.
+     */
     const char		*nat_type_name;
+
 } pj_stun_nat_detect_result;
 
 
@@ -75,7 +152,26 @@ typedef void pj_stun_nat_detect_cb(void *user_data,
 
 
 /**
- * Perform NAT classification function.
+ * Perform NAT classification function according to the procedures
+ * specified in RFC 3489. Once this function returns successfully,
+ * the procedure will run in the "background" and will complete
+ * asynchronously. Application can register a callback to be notified
+ * when such detection has completed.
+ *
+ * @param server	STUN server address.
+ * @param stun_cfg	A structure containing various STUN configurations,
+ *			such as the ioqueue and timer heap instance used
+ *			to receive network I/O and timer events.
+ * @param user_data	Application data, which will be returned back
+ *			in the callback.
+ * @param cb		Callback to be registered to receive notification
+ *			about detection result.
+ *
+ * @return		If this function returns PJ_SUCCESS, the procedure
+ *			will complete asynchronously and callback will be
+ *			called when it completes. For other return
+ *			values, it means that an error has occured and
+ *			the procedure did not start.
  */
 PJ_DECL(pj_status_t) pj_stun_detect_nat_type(const pj_sockaddr_in *server,
 					     pj_stun_config *stun_cfg,
diff --git a/pjnath/src/pjnath/nat_detect.c b/pjnath/src/pjnath/nat_detect.c
index 11e933a5..29549465 100644
--- a/pjnath/src/pjnath/nat_detect.c
+++ b/pjnath/src/pjnath/nat_detect.c
@@ -41,11 +41,9 @@ static const char *nat_type_names[] =
 };
 
 
-//#define CHANGE_PORT	    (0x01 << 30)
-//#define CHANGE_ADDR_PORT    (0x03 << 29)
-//#define CHANGE_ADDR_PORT	0xFFFFFFFFU
+#define CHANGE_ADDR		4
 #define CHANGE_PORT		2
-#define CHANGE_ADDR_PORT	6
+#define CHANGE_ADDR_PORT	(CHANGE_ADDR | CHANGE_PORT)
 
 
 enum state