/* $Id$ */ /* * Copyright (C) 2008-2009 Teluu Inc. (http://www.teluu.com) * Copyright (C) 2003-2008 Benny Prijono * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ #ifndef __PJNATH_NAT_DETECT_H__ #define __PJNATH_NAT_DETECT_H__ /** * @file ice_session.h * @brief ICE session management */ #include PJ_BEGIN_DECL /** * @defgroup PJNATH_NAT_DETECT NAT Classification/Detection Tool * @brief NAT Classification/Detection Tool * @{ * * This module provides one function to perform NAT classification and * detection. NAT type detection is performed by calling * #pj_stun_detect_nat_type() function. */ /** * 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 not been performed. */ PJ_STUN_NAT_TYPE_UNKNOWN, /** * NAT type is unknown because there is failure in the detection * process, possibly because server does not support RFC 3489. */ PJ_STUN_NAT_TYPE_ERR_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; /** * This structure contains the result of NAT classification function. */ 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; /** * Type of callback to be called when the NAT detection function has * completed. */ typedef void pj_stun_nat_detect_cb(void *user_data, const pj_stun_nat_detect_result *res); /** * Get the NAT name from the specified NAT type. * * @param type NAT type. * * @return NAT name. */ PJ_DECL(const char*) pj_stun_get_nat_name(pj_stun_nat_type type); /** * 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, void *user_data, pj_stun_nat_detect_cb *cb); /** * @} */ PJ_END_DECL #endif /* __PJNATH_NAT_DETECT_H__ */