diff options
Diffstat (limited to 'pjnath/include')
-rw-r--r-- | pjnath/include/pjnath/nat_detect.h | 102 |
1 files changed, 99 insertions, 3 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, |