voice-gateway/pjnath/docs/doc_mainpage.h

/* 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 *
 * 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 
 */


/**

@mainpage PJNATH - Open Source ICE, STUN, and TURN Library

PJNATH (PJSIP NAT Helper) is an open source library providing NAT traversal 
functionalities by using standard based protocols such as STUN, TURN, and ICE.


\section background Background


Network Address Translation (NAT) is commonly deployed everywhere primarily to
alleviate the exhaustion of IPv4 address space by allowing multiple hosts to 
share a public/Internet address. While NAT would work well for typical client 
server communications (such as web and email), since it's always the client 
that initiates the conversation and normally client doesn't need to maintain
the connection for a long time, installation of NAT would cause major problem
for peer-to-peer communication, such as (and especially) VoIP. 

<strong>\ref nat_intro "Read more.."</strong>


\section pjnath_intro Introduction to PJNATH

PJSIP NAT Helper (PJNATH) is a library which contains the implementation of 
standard based NAT traversal solutions. PJNATH can be used as a stand-alone 
library for your software, or you may use PJSUA-LIB library, a very high level
 library integrating PJSIP, PJMEDIA, and PJNATH into simple to use APIs.

PJNATH has the following features:

 - <strong>STUNbis</strong> implementation,\n
   providing both ready to use 
   STUN-aware socket and framework to implement higher level STUN based 
   protocols such as TURN and ICE. The implementation complies to 
   <A HREF="http://www.ietf.org/rfc/rfc5389.txt">RFC 5389</A>
   standard.\n\n

 - <strong>NAT type detection</strong>, \n
   performs detection of the NAT type in front of the endpoint, according
   to <A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>. 
   While the practice to detect the NAT type to assist NAT 
   traversal has been deprecated in favor of ICE, the information may still
   be useful for troubleshooting purposes, hence the utility is provided.\n\n

 - <strong>Traversal Using Relays around NAT (TURN)</strong> implementation.\n
   TURN is a protocol for relaying communications by means of using relay, 
   and combined with ICE it provides efficient last effort alternative for 
   the communication path. The TURN implementation in PJNATH complies to 
   <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-14.txt">
   draft-ietf-behave-turn-14</A> draft.\n\n

 - <strong>Interactive Connectivity Establishmen (ICE)</strong> implementation.\n
   ICE is a protocol for discovering communication path(s) between two 
   endpoints. The implementation in PJNATH complies to
   <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-19.txt">
   draft-ietf-mmusic-ice-19.txt</A> draft

 - <strong>Universal Plug and Play (UPnP)</strong> control point implementation.\n
   Universal Plug and Play (UPnP) Internet Gateway Device (IGD) Protocol
   allows any local UPnP control point to retrieve the external IP address of
   the device, and add or remove port mappings. By adding a port mapping,
   a UPnP controller behind the IGD can enable traversal of the IGD from
   an external address to an internal client.\n\n


\section pjnath_organization_sec Library Organization

The library provides the following main component groups:

 - \ref PJNATH_STUN \n\n
 - \ref PJNATH_TURN \n\n
 - \ref PJNATH_ICE \n\n
 - \ref PJNATH_NAT_DETECT \n\n
 - \ref PJNATH_UPNP \n\n

Apart from the \ref PJNATH_NAT_DETECT and \ref PJNATH_UPNP, each component
group are further divided into two functionalities:

 - <b>Transport objects</b>\n
   The transport objects (such as STUN transport, TURN transport, and ICE
   stream transport) are the implementation of the session object
   <strong>with</strong> particular transport/sockets. They are provided
   as ready to use objects for applications.\n\n

 - <b>Transport independent/session layer</b>\n
   The session objects (such as STUN session, TURN session, and ICE session)
   are the core object for maintaining the protocol session, and it is
   independent of transport (i.e. it does not "own" a socket). This way
   developers can reuse these session objects for any kind of transports,
   such as UDP, TCP, or TLS, with or without using PJLIB socket API.
   The session objects provide function and callback to send and receive
   packets respectively.

For more information about each component groups, please click the component
link above.


\section pjnath_start_sec Getting Started with PJNATH

\subsection dependency Library Dependencies

The PJNATH library depends (and only depends) on PJLIB and PJLIB-UTIL
libraries. All these libraries should have been packaged together with
the main PJSIP distribution. You can download the PJSIP distribution
from <A HREF="http://www.pjsip.org">PJSIP website</A>


\subsection pjnath_using_sec Using the libraries

Please click on the appropriate component under \ref pjnath_organization_sec
section above, which will take you to the documentation on how to use the 
component.


\subsection samples_sec Samples

We attempt to provide simple samples to use each functionality of the PJNATH
library.

Please see <b>\ref samples_page</b> page for the list of samples.


*/



/**
@defgroup samples_page PJNATH Samples and screenshots
@brief Sample applications and screenshots
 */