Changeset 1497 for pjproject/trunk

Timestamp:

Oct 12, 2007 11:29:27 PM (17 years ago)

Author:

bennylp

Message:

Related to ticket #399: added comments etc.

Location:

pjproject/trunk

Files:

• pjnath/include/pjnath/nat_detect.h (modified) (3 diffs)
• pjnath/src/pjnath/nat_detect.c (modified) (1 diff)
• pjsip-apps/src/pjsua_wince/pjsua_wince.cpp (modified) (1 diff)

pjproject/trunk/pjnath/include/pjnath/nat_detect.h

@@ -35 +35 @@
  * @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;
 
@@ -60 +118 @@
 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;
 
@@ -76 +153 @@
 
 /**
- * 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,

pjproject/trunk/pjnath/src/pjnath/nat_detect.c

@@ -42 +42 @@
 
 
-//#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)
 
 

pjproject/trunk/pjsip-apps/src/pjsua_wince/pjsua_wince.cpp

@@ -54 +54 @@
 //
 // STUN server
-#if 0
+#if 1
         // Use this to have the STUN server resolved normally
 #   define STUN_DOMAIN  NULL
-#   define STUN_SERVER  "192.168.0.2"
+#   define STUN_SERVER  "stun.fwdnet.net"
 #elif 0
         // Use this to have the STUN server resolved with DNS SRV