Ignore:
Timestamp:
Jun 6, 2008 2:47:10 PM (14 years ago)
Author:
bennylp
Message:

Major major modifications related to ticket #485 (support for TURN-07):

  • Added STUN socket transport pj_stun_sock
  • Integration of TURN-07 to ICE
  • Major refactoring in ICE stream transport to make it simpler
  • Major modification (i.e. API change) in almost everywhere else
  • Much more elaborate STUN, TURN, and ICE tests in pjnath-test
File:
1 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjnath/include/pjnath/types.h

    r1914 r1988  
    3636 
    3737/** 
     38 * This constant describes a number to be used to identify an invalid TURN 
     39 * channel number. 
     40 */ 
     41#define PJ_TURN_INVALID_CHANNEL     0xFFFF 
     42 
     43 
     44/** 
    3845 * Initialize pjnath library. 
    3946 * 
     
    4451 
    4552/** 
    46  * Display error to the log. 
     53 * Display error to the log.  
    4754 * 
    4855 * @param sender    The sender name. 
     
    6875 
    6976/** 
    70  * @mainpage PJNATH - Open Source ICE, STUN, and TURN Library 
    71  * 
    72  * \n 
    73  * This is the documentation of PJNATH, an Open Source library providing 
    74  * NAT traversal helper functionalities by using standard based protocols. 
    75  * 
    76  * \n 
    77  
    78  * \section PJNATH_STUN STUN Protocol Library 
    79  * 
    80  * Session Traversal Utilities (STUN, or previously known as Simple  
    81  * Traversal of User Datagram Protocol (UDP) Through Network Address  
    82  * Translators (NAT)s), is a lightweight protocol that serves as a tool for 
    83  * application protocols in dealing with NAT traversal. It allows a client 
    84  * to determine the IP address and port allocated to them by a NAT and to  
    85  * keep NAT bindings open. 
    86  *  
    87  * The PJNATH library provides facilities to support both the core  
    88  * <B>STUN-bis</B> specification and the <B>TURN</B> usage of STUN,  
    89  * as well as other STUN usages. Please see #pj_stun_attr_type for  
    90  * list of STUN attributes supported by this library. 
    91  * 
    92  *  
    93  * The following are some design principles that have been utilized 
    94  * when implementing the STUN library in PJNATH: 
    95  * 
    96  *  - layered architecture, with \ref PJNATH_STUN_MSG as the lowest 
    97  *    layer and \ref PJNATH_STUN_SESSION as the highest abstraction 
    98  *    layer, to accommodate various usage scenario of the library. 
    99  * 
    100  *  - no transport -- the STUN library is pretty much transport 
    101  *    independent and all sending and receiving functionalities will 
    102  *    have to be implemented by application or higher level 
    103  *    abstraction (such as ICE). This helps facilitating an even 
    104  *    more usage scenarios of the library. 
    105  * 
    106  *  - common functionalities for both STUN client and server 
    107  *    development. All STUN components can be used to develop both 
    108  *    STUN client and STUN server application, and in fact, in ICE, 
    109  *    both STUN client and server functionality exist in a single 
    110  *    ICE session. 
    111  * 
    112  * \n 
    113  * 
    114  * \subsection PJNATH_STUN_ARCH STUN Library Organization 
    115  * 
    116  * \image html stun-arch.jpg "STUN Library Architecture" 
    117  * 
    118  * The STUN library is organized as follows: 
    119  * 
    120  *  - for both client and server, the highest abstraction is 
    121  *    \ref PJNATH_STUN_SESSION, which provides management of incoming 
    122  *    and outgoing messages and association of STUN credential to 
    123  *    a STUN session.  
    124  * 
    125  *  - for client, the next layer below is \ref PJNATH_STUN_TRANSACTION, 
    126  *    which manages retransmissions of STUN request. Server side STUN 
    127  *    transaction is handled in \ref PJNATH_STUN_SESSION layer above. 
    128  * 
    129  *  - \ref PJNATH_STUN_AUTH provides mechanism to verify STUN 
    130  *    credential in incoming STUN messages. 
    131  * 
    132  *  - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer 
    133  *    provides STUN message representation, validation, parsing,  
    134  *    encoding MESSAGE-INTEGRITY for outgoing messages, and 
    135  *    debugging (dump to log) of STUN messages. 
    136  * 
    137  * All STUN library components are independent of any transports.  
    138  * Application gives incoming packet to the STUN components for processing, 
    139  * and it must supply the STUN components with callback to send outgoing  
    140  * messages. 
    141  *  
    142  * 
    143  * \n 
    144  * 
    145  * \subsection PJNATH_STUN_CLASSES PJNATH Class Diagram 
    146  * 
    147  *  
    148  * \image html UML-class-diagram.png "Class Diagram" 
    149  * 
    150  * TBD: write descriptions. 
    151  * 
    152  * \subsection PJNATH_STUN_USING Using STUN Library 
    153  * 
    154  * [The developers guide documentation can certainly be improved here] 
    155  * 
    156  * For a sample STUN and TURN client, please see <tt>pjstun-client</tt> 
    157  * project under <tt>pjnath/src</tt> directory. 
    158  * 
    159  * For a sample STUN and TURN server, please see <tt>pjstun-srv-test</tt> 
    160  * project under <tt>pjnath/src</tt> directory. 
    161  * 
    162  * 
    163  * \subsection PJNATH_STUN_REF STUN Reference 
    164  * 
    165  * References for STUN: 
    166  * 
    167  *  - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-rfc3489bis-15.txt"> 
    168  *    <B>draft-ietf-behave-rfc3489bis-15</b></A>: Session Traversal  
    169  *     Utilities for (NAT) (STUN), 
    170  *  - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-07.txt"> 
    171  *    <B>draft-ietf-behave-turn-07</B></A>: Obtaining Relay Addresses  
    172  *    from Simple Traversal Underneath NAT (STUN) 
    173  *  - Obsoleted: <A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>. 
    174  * 
    175  * \n 
    176  * 
    177  * \section PJNATH_ICE ICE Implementation 
    178  * 
    179  * Interactive Connectivity Establishment (ICE) is a standard based  
    180  * methodology for traversing Network Address Translator (NAT), and 
    181  * is described in  
    182  * <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-19.txt"> 
    183  * <B>draft-ietf-mmusic-ice-19.txt</B></A> draft. The PJNATH ICE 
    184  * implementation is aimed to provide a usable and generic ICE transports 
    185  * for different types of application, including but not limited to 
    186  * the usage of ICE in SIP/SDP offer/answer. 
    187  *  
    188  * 
    189  * \subsection PJNATH_ICE_ARCH ICE Library Organization 
    190  *  
    191  * \image html ice-arch.jpg "ICE Architecture" 
    192  * 
    193  * The ICE library is organized as follows: 
    194  * 
    195  *  - the highest abstraction is ICE media transport, which maintains 
    196  *    ICE stream transport and provides SDP translations to be used 
    197  *    for SIP offer/answer exchanges. ICE media transport is part 
    198  *    of PJMEDIA library. 
    199  * 
    200  *  - higher in the hierarchy is \ref PJNATH_ICE_STREAM_TRANSPORT, 
    201  *    which binds ICE with UDP sockets, and provides STUN binding 
    202  *    and relay/TURN allocation for the sockets. This component can 
    203  *    be directly used by application, although normally application 
    204  *    should use the next higher abstraction since it provides 
    205  *    SDP translations and better integration with other PJ libraries 
    206  *    such as PJSIP and PJMEDIA. 
    207  * 
    208  *  - the lowest layer is \ref PJNATH_ICE_SESSION, which provides  
    209  *    ICE management and negotiation in a transport-independent way. 
    210  *    This layer contains the state machines to perform ICE 
    211  *    negotiation, and provides the most flexibility to control all 
    212  *    aspects of ICE session. This layer normally is only usable for 
    213  *    ICE implementors. 
    214  * 
    215  * \subsection PJNATH_ICE_USING Using the ICE Library 
    216  * 
    217  * For ICE implementation that has been integrated with socket transport, 
    218  * please see \ref PJNATH_ICE_STREAM_TRANSPORT_USING. 
    219  * 
    220  * For ICE implementation that has not been integrated with socket 
    221  * transport, please see \ref pj_ice_sess_using_sec. 
    222  * 
    223  * \subsection PJNATH_ICE_REF Reference 
    224  * 
    225  * References for ICE: 
    226  *  - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-19.txt"> 
    227  *    <B>draft-ietf-mmusic-ice-19.txt</B></A>: Interactive Connectivity  
    228  *    Establishment (ICE): A Methodology for Network Address Translator  
    229  *    (NAT) Traversal for Offer/Answer Protocols 
    230  */ 
     77 
     78@mainpage PJNATH - Open Source ICE, STUN, and TURN Library 
     79 
     80\n 
     81This is the documentation of PJNATH, an Open Source library providing 
     82NAT traversal helper functionalities by using standard based protocols 
     83such as STUN, TURN, and ICE. 
     84 
     85\n 
     86\n 
     87 
     88\section lib_comps Library Components 
     89 
     90\subsection comp_stun STUN 
     91 
     92Session Traversal Utilities (STUN, or previously known as Simple  
     93Traversal of User Datagram Protocol (UDP) Through Network Address  
     94Translators (NAT)s), is a lightweight protocol that serves as a tool for 
     95application protocols in dealing with NAT traversal. It allows a client 
     96to determine the IP address and port allocated to them by a NAT and to  
     97keep NAT bindings open. 
     98 
     99This version of PJNATH implements the following STUN-bis draft: 
     100- <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-rfc3489bis-15.txt"> 
     101  <B>draft-ietf-behave-rfc3489bis-15</b></A>: Session Traversal  
     102    Utilities for (NAT) (STUN), 
     103 
     104 
     105\subsection comp_turn TURN 
     106 
     107Traversal Using Relays around NAT (TURN) allows the host to control the 
     108operation of the relay and to exchange packets with its peers using the relay. 
     109 
     110This version of PJNATH implements both TCP and UDP client transport and it 
     111complies with the following TURN draft: 
     112 - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-07.txt"> 
     113   <B>draft-ietf-behave-turn-07</B></A>: Obtaining Relay Addresses  
     114   from Simple Traversal Underneath NAT (STUN) 
     115 
     116 
     117\subsection comp_ice ICE 
     118 
     119Interactive Connectivity Establishment (ICE) is a standard based  
     120methodology for traversing Network Address Translator (NAT). This 
     121implementation is aimed to provide a usable and generic ICE transports 
     122for different types of application, including but not limited to 
     123the usage of ICE in SIP/SDP offer/answer. 
     124 
     125 
     126This version of PJNATH implements the following ICE draft: 
     127 - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-19.txt"> 
     128   <B>draft-ietf-mmusic-ice-19.txt</B></A> draft. The PJNATH ICE 
     129 
     130 
     131\subsection comp_natck NAT Classification Utility 
     132 
     133The PJNATH library also provides NAT classification utility as  
     134described in <A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>. 
     135While the practice to detect the NAT type to assist NAT traversal 
     136has been deprecated in favor of ICE, the information may still be 
     137useful for troubleshooting purposes, hence the utility is provided. 
     138 
     139 
     140\n 
     141\n 
     142 
     143\section lib_org Library Organization 
     144 
     145The PJNATH library consists of many components with each providing 
     146specific functionality that may or may not be of the interests of  
     147applications (or application developers). This section attempts to  
     148give brief overview on the components provided by PJNATH. 
     149 
     150The PJNATH components from the highest layer to the lower layer are 
     151as follows. 
     152 
     153 
     154\n 
     155 
     156\subsection user_comp High-level Transport Objects 
     157 
     158PJNATH library provides some high-level objects that may be used 
     159by applications: 
     160 
     161 
     162\subsubsection stun_sock STUN Transport 
     163 
     164The \ref PJNATH_STUN_SOCK provides asynchronous UDP like socket transport 
     165with the additional capability to query the publicly mapped transport 
     166address (using STUN resolution), to refresh the NAT binding, and to 
     167demultiplex internal STUN messages from application data (the  
     168application data may be a STUN message as well). 
     169 
     170 
     171\subsubsection turn_sock TURN Client Transport 
     172 
     173The \ref PJNATH_TURN_SOCK may be used by the application to send and 
     174receive data via TURN server. For more information please see the 
     175documentation of \ref PJNATH_TURN_SOCK. 
     176 
     177 
     178\subsubsection ice_strans ICE Stream Transport 
     179 
     180The \ref PJNATH_ICE_STREAM_TRANSPORT provides transport interface to 
     181send and receive data through connection that is negotiated 
     182with ICE protocol. The \ref PJNATH_ICE_STREAM_TRANSPORT naturally  
     183contains both STUN Transport and \ref PJNATH_TURN_SOCK. 
     184 
     185The \ref PJNATH_ICE_STREAM_TRANSPORT interface is suitable for both 
     186SIP or non-SIP use. For SIP use, application may prefer to use the 
     187ICE media transport in PJMEDIA instead where it has been integrated 
     188with the SDP offer and answer mechanism. 
     189 
     190 
     191\subsubsection natck NAT Classification Utility 
     192 
     193PJNATH also provides \a PJNATH_NAT_DETECT to assist troubleshooting 
     194of problems related to NAT traversal. 
     195 
     196 
     197 
     198\n 
     199 
     200 
     201\subsection sessions Transport Independent Sessions Layer 
     202 
     203Right below the high level transports objects are the transport 
     204independent sessions. These sessions don't have access to sockets, 
     205so higher level objects (such as transports) must give incoming 
     206packets to the sessions and provide callback to be called by 
     207sessions to send outgoing packets. 
     208 
     209 
     210\subsubsection ice_sess ICE Session 
     211 
     212The \ref PJNATH_ICE_SESSION is used by the \ref PJNATH_ICE_STREAM_TRANSPORT 
     213and contains the actual logic of the ICE negotiation. 
     214 
     215 
     216\subsubsection turn_sess TURN Session 
     217 
     218The \ref PJNATH_TURN_SESSION is used by the \ref PJNATH_TURN_SOCK 
     219and it contains TURN protocol logic. Implementors may implement 
     220other types of TURN client connection (such as TURN TLS client) 
     221by utilizing this session. 
     222 
     223 
     224\subsubsection stun_sess STUN Session 
     225 
     226The \ref PJNATH_STUN_SESSION manages STUN message exchange between 
     227a client and server (or vice versa). It manages \ref PJNATH_STUN_TRANSACTION 
     228for sending or receiving requests and \ref PJNATH_STUN_AUTH for both 
     229both incoming and outgoing STUN messages.  
     230 
     231The \ref PJNATH_STUN_SESSION is naturally used by the \ref PJNATH_TURN_SESSION 
     232and \ref PJNATH_ICE_SESSION 
     233 
     234 
     235\n 
     236 
     237\subsection stun_tsx STUN Transaction Layer 
     238 
     239The \ref PJNATH_STUN_TRANSACTION is a thin layer to manage retransmission 
     240of STUN requests. 
     241 
     242 
     243\n 
     244 
     245 
     246\subsection stun_msg STUN Messaging Layer 
     247 
     248At the very bottom of the PJNATH components is the \ref PJNATH_STUN_MSG 
     249layer. The API contains various representation of STUN messaging components 
     250and it provides API to encode and decode STUN messages. 
     251 
     252 
     253 
     254\n 
     255\n 
     256 
     257\section class_dia Class Diagram 
     258 
     259 
     260The following class diagram shows the interactions between objects in 
     261PJNATH: 
     262 
     263\image html UML-class-diagram.png "Class Diagram" 
     264\image latex UML-class-diagram.png "Class Diagram" 
     265 
     266 
     267 
     268\n 
     269\n 
     270 
     271\section samples Sample Applications 
     272 
     273 
     274Some sample applications have been provided with PJNATH, and it's available 
     275under <tt>pjnath/src</tt> directory: 
     276 
     277   - <b>pjturn-client</b>: this is a stand-alone, console based TURN client 
     278     application to be used as a demonstration for PJNATH TURN client  
     279     transport API and for simple testing against TURN server implementations. 
     280     The client supports both UDP and TCP connection to the TURN server. 
     281 
     282   - <b>pjturn-srv</b>: this is a simple TURN server to be used for testing 
     283     purposes. It supports both UDP and TCP connections to the clients. 
     284 
     285 
     286*/ 
    231287 
    232288/** 
Note: See TracChangeset for help on using the changeset viewer.