Index: /pjproject/trunk/pjnath/build/pjnath.dsp
===================================================================
--- /pjproject/trunk/pjnath/build/pjnath.dsp	(revision 2641)
+++ /pjproject/trunk/pjnath/build/pjnath.dsp	(revision 2642)
@@ -201,4 +201,32 @@
 # End Source File
 # End Group
+# Begin Group "Doxygen Files"
+
+# PROP Default_Filter ""
+# Begin Source File
+
+SOURCE=..\docs\doc_ice.h
+# End Source File
+# Begin Source File
+
+SOURCE=..\docs\doc_mainpage.h
+# End Source File
+# Begin Source File
+
+SOURCE=..\docs\doc_nat.h
+# End Source File
+# Begin Source File
+
+SOURCE=..\docs\doc_samples.h
+# End Source File
+# Begin Source File
+
+SOURCE=..\docs\doc_stun.h
+# End Source File
+# Begin Source File
+
+SOURCE=..\docs\doc_turn.h
+# End Source File
+# End Group
 # End Target
 # End Project
Index: /pjproject/trunk/pjnath/build/pjnath.vcproj
===================================================================
--- /pjproject/trunk/pjnath/build/pjnath.vcproj	(revision 2641)
+++ /pjproject/trunk/pjnath/build/pjnath.vcproj	(revision 2642)
@@ -23,35 +23,30 @@
 		<Configuration
 			Name="Release|Win32"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-win32-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			UseOfMFC="0"
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="2"
-
-			ConfigurationType="4"
-			UseOfMFC="0"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
 				AdditionalIncludeDirectories="../include,../../pjlib/include,../../pjlib-util/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -85,34 +80,30 @@
 		<Configuration
 			Name="Release|Windows Mobile 6 Standard SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -128,6 +119,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6std-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -157,34 +146,30 @@
 		<Configuration
 			Name="Release|Windows Mobile 6 Professional SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -200,6 +185,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6pro-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -229,35 +212,30 @@
 		<Configuration
 			Name="Debug|Win32"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-win32-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			UseOfMFC="0"
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="2"
-
-			ConfigurationType="4"
-			UseOfMFC="0"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
 				AdditionalIncludeDirectories="../include,../../pjlib/include,../../pjlib-util/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -291,34 +269,30 @@
 		<Configuration
 			Name="Debug|Windows Mobile 6 Standard SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -334,6 +308,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6std-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -363,34 +335,30 @@
 		<Configuration
 			Name="Debug|Windows Mobile 6 Professional SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -406,6 +374,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6pro-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -435,35 +401,30 @@
 		<Configuration
 			Name="Debug-Static|Win32"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-win32-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			UseOfMFC="0"
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="2"
-
-			ConfigurationType="4"
-			UseOfMFC="0"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
 				AdditionalIncludeDirectories="../include,../../pjlib/include,../../pjlib-util/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -497,34 +458,30 @@
 		<Configuration
 			Name="Debug-Static|Windows Mobile 6 Standard SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -540,6 +497,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6std-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -569,34 +524,30 @@
 		<Configuration
 			Name="Debug-Static|Windows Mobile 6 Professional SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -612,6 +563,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6pro-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -641,35 +590,30 @@
 		<Configuration
 			Name="Release-Dynamic|Win32"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-win32-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			UseOfMFC="0"
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="2"
-
-			ConfigurationType="4"
-			UseOfMFC="0"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
 				AdditionalIncludeDirectories="../include,../../pjlib/include,../../pjlib-util/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -703,34 +647,30 @@
 		<Configuration
 			Name="Release-Dynamic|Windows Mobile 6 Standard SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -746,6 +686,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6std-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -775,34 +713,30 @@
 		<Configuration
 			Name="Release-Dynamic|Windows Mobile 6 Professional SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -818,6 +752,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6pro-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -847,35 +779,30 @@
 		<Configuration
 			Name="Debug-Dynamic|Win32"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-win32-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			UseOfMFC="0"
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="2"
-
-			ConfigurationType="4"
-			UseOfMFC="0"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
 				AdditionalIncludeDirectories="../include,../../pjlib/include,../../pjlib-util/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -909,34 +836,30 @@
 		<Configuration
 			Name="Debug-Dynamic|Windows Mobile 6 Standard SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -952,6 +875,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6std-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -981,34 +902,30 @@
 		<Configuration
 			Name="Debug-Dynamic|Windows Mobile 6 Professional SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-debug-dynamic-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-common-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -1024,6 +941,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6pro-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -1053,35 +968,30 @@
 		<Configuration
 			Name="Release-Static|Win32"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-win32-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			UseOfMFC="0"
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="2"
-
-			ConfigurationType="4"
-			UseOfMFC="0"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
 				AdditionalIncludeDirectories="../include,../../pjlib/include,../../pjlib-util/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -1115,34 +1025,30 @@
 		<Configuration
 			Name="Release-Static|Windows Mobile 6 Standard SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -1158,6 +1064,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6std-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -1187,34 +1091,30 @@
 		<Configuration
 			Name="Release-Static|Windows Mobile 6 Professional SDK (ARMV4I)"
+			ConfigurationType="4"
 			InheritedPropertySheets="..\..\build\vs\pjproject-vs8-release-static-defaults.vsprops;..\..\build\vs\pjproject-vs8-wm6-release-defaults.vsprops"
-
-			ATLMinimizesCRunTimeLibraryUsage="false"
-
+			ATLMinimizesCRunTimeLibraryUsage="false"
 			CharacterSet="1"
-
-			ConfigurationType="4"
-			>
-			<Tool
-				Name="VCPreBuildEventTool"
-			/>
-			<Tool
-				Name="VCCustomBuildTool"
-			/>
-			<Tool
-				Name="VCXMLDataGeneratorTool"
-			/>
-			<Tool
-				Name="VCWebServiceProxyGeneratorTool"
-			/>
-			<Tool
-				Name="VCMIDLTool"
-			/>
-			<Tool
-				Name="VCCLCompilerTool"
-				PrecompiledHeaderFile=""
-
-				PreprocessorDefinitions="_LIB;"
-
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				ExecutionBucket="7"
 				AdditionalIncludeDirectories="../include,../../pjlib-util/include,../../pjlib/include"
+				PreprocessorDefinitions="_LIB;"
+				PrecompiledHeaderFile=""
 			/>
 			<Tool
@@ -1230,6 +1130,4 @@
 				Name="VCLibrarianTool"
 				OutputFile="..\lib\$(ProjectName)-$(TargetCPU)-wm6pro-vs$(VSVer)-$(ConfigurationName).lib"
-
-
 			/>
 			<Tool
@@ -1703,4 +1601,32 @@
 			</File>
 		</Filter>
+		<Filter
+			Name="Doxygen Files"
+			>
+			<File
+				RelativePath="..\docs\doc_ice.h"
+				>
+			</File>
+			<File
+				RelativePath="..\docs\doc_mainpage.h"
+				>
+			</File>
+			<File
+				RelativePath="..\docs\doc_nat.h"
+				>
+			</File>
+			<File
+				RelativePath="..\docs\doc_samples.h"
+				>
+			</File>
+			<File
+				RelativePath="..\docs\doc_stun.h"
+				>
+			</File>
+			<File
+				RelativePath="..\docs\doc_turn.h"
+				>
+			</File>
+		</Filter>
 	</Files>
 	<Globals>
Index: /pjproject/trunk/pjnath/docs/doc_ice.h
===================================================================
--- /pjproject/trunk/pjnath/docs/doc_ice.h	(revision 2642)
+++ /pjproject/trunk/pjnath/docs/doc_ice.h	(revision 2642)
@@ -0,0 +1,107 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2008-2009 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 
+ */
+
+/**
+@defgroup PJNATH_ICE ICE: Interactive Connectivity Establishment
+@brief Interactive Connectivity Establishment (ICE)
+@ingroup PJNATH
+*/
+
+/**
+@defgroup PJNATH_ICE_STREAM_TRANSPORT ICE stream transport
+@brief Transport for media streams using ICE
+@ingroup PJNATH_ICE
+ */
+
+/**
+@defgroup PJNATH_ICE_SESSION ICE Session
+@brief Transport Independent ICE Session
+@ingroup PJNATH_ICE
+ */
+
+/**
+@addtogroup PJNATH_ICE
+\section org Library organizations
+
+See <b>Table of Contents</b> below.
+
+\section ice_intro_sec Introduction to ICE
+
+Interactive Connectivity Establishment (ICE) is the ultimate 
+weapon a client can have in its NAT traversal solution arsenals, 
+as it promises that if there is indeed one path for two clients 
+to communicate, then ICE will find this path. And if there are 
+more than one paths which the clients can communicate, ICE will 
+use the best/most efficient one.
+
+ICE works by combining several protocols (such as STUN and TURN) 
+altogether and offering several candidate paths for the communication,
+thereby maximising the chance of success, but at the same time also 
+has the capability to prioritize the candidates, so that the more 
+expensive alternative (namely relay) will only be used as the last
+resort when else fails. ICE negotiation process involves several 
+stages:
+
+ - candidate gathering, where the client finds out all the possible 
+   addresses that it can use for the communication. It may find 
+   three types of candidates: host candidate to represent its 
+   physical NICs, server reflexive candidate for the address that 
+   has been resolved from STUN, and relay candidate for the address 
+   that the client has allocated from a TURN relay.
+ - prioritizing these candidates. Typically the relay candidate will
+   have the lowest priority to use since it's the most expensive.
+ - encoding these candidates, sending it to remote peer, and 
+   negotiating it with offer-answer.
+ - pairing the candidates, where it pairs every local candidates 
+   with every remote candidates that it receives from the remote peer.
+ - checking the connectivity for each candidate pairs.
+ - concluding the result. Since every possible path combinations are 
+   checked, if there is a path to communicate ICE will find it.
+
+
+\section icestrans_sec Using ICE transport
+
+The \ref PJNATH_ICE_STREAM_TRANSPORT is a ready to use object which
+performs the above ICE operations as well as provides application with
+interface to send and receive data using the negotiated path.
+
+Please see \ref PJNATH_ICE_STREAM_TRANSPORT on how to use this object.
+
+
+\section ice_owntransport_sec Creating custom ICE transport
+
+If the \ref PJNATH_ICE_STREAM_TRANSPORT is not suitable for use 
+for some reason, you will need to implement your own ICE transport,
+by combining the \ref PJNATH_ICE_SESSION with your own means to
+send and receive packets. The \ref PJNATH_ICE_STREAM_TRANSPORT 
+provides the best example on how to do this.
+
+
+\section ice_samples_sec Samples
+
+The \ref ice_demo_sample sample demonstrates how to use 
+\ref PJNATH_ICE_STREAM_TRANSPORT <b>without</b> using signaling 
+protocol such as <b>SIP</b>. It provides  interactive user interface
+to create and manage the ICE sessions as well as to exchange SDP 
+with another ice_demo instance.
+
+Also see <b>\ref samples_page</b> for other samples.
+ */
+
+
Index: /pjproject/trunk/pjnath/docs/doc_mainpage.h
===================================================================
--- /pjproject/trunk/pjnath/docs/doc_mainpage.h	(revision 2642)
+++ /pjproject/trunk/pjnath/docs/doc_mainpage.h	(revision 2642)
@@ -0,0 +1,148 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2008-2009 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 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-13.txt">
+   draft-ietf-behave-turn-13</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
+
+In the future, more protocols will be implemented (such as UPnP IGD, and 
+SOCKS5).
+
+
+\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
+
+Apart from the \ref PJNATH_NAT_DETECT, 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
+ */
+
+
Index: /pjproject/trunk/pjnath/docs/doc_nat.h
===================================================================
--- /pjproject/trunk/pjnath/docs/doc_nat.h	(revision 2642)
+++ /pjproject/trunk/pjnath/docs/doc_nat.h	(revision 2642)
@@ -0,0 +1,415 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2008-2009 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 
+ */
+
+
+/**
+
+@defgroup nat_intro Introduction to Network Address Translation (NAT) and NAT Traversal
+@brief This page describes NAT and the problems caused by it and the solutions
+
+
+
+\section into Introduction to NAT
+
+
+NAT (Network Address Translation) is a mechanism where a device performs 
+modifications to the TCP/IP address/port number of a packet and maps the 
+IP address from one realm to another (usually from private IP address to 
+public IP address and vice versa). This works by the NAT device allocating
+a temporary port number on the public side of the NAT upon forwarding 
+outbound packet from the internal host towards the Internet, maintaining
+this mapping for some predefined time, and forwarding the inbound packets
+received from the Internet on this public port back to the internal host.
+
+
+NAT devices are installed primarily to alleviate the exhaustion of IPv4 
+address space by allowing multiple hosts to share a public/Internet address.
+Also due to its mapping nature (i.e. a mapping can only be created by 
+a transmission from an internal host), NAT device is preferred to be 
+installed even when IPv4 address exhaustion is not a problem (for example
+when there is only one host at home), to provide some sort of security/shield
+for the internal hosts against threats from the Internet.
+
+
+Despite the fact that NAT provides some shields for the internal network,
+one must distinguish NAT solution from firewall solution. NAT is not 
+a firewall solution. A firewall is a security solution designed to enforce
+the security policy of an organization, while NAT is a connectivity solution
+to allow multiple hosts to use a single public IP address. Understandably
+both functionalities are difficult to separate at times, since many 
+(typically consumer) products claims to do both with the same device and
+simply label the device a NAT box. But we do want to make this distinction
+rather clear, as PJNATH is a NAT traversal helper and not a firewall bypass
+solution (yet).
+
+
+
+\section problems The NAT traversal problems
+
+
+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. These problems will be explained in more detail
+below.
+
+
+\subsection peer_addr Peer address problem
+
+
+In VoIP, normally we want the media (audio, and video) to flow directly
+between the clients, since relaying is costly (both in terms of bandwidth
+cost for service provider, and additional latency introduced by relaying).
+To do this, each client informs its media transport address to the other
+client , by sending it via the VoIP signaling path, and the other side would
+send its media to this transport address.
+
+
+And there lies the problem. If the client software is not NAT aware, then
+it would send its private IP address to the other client, and the other
+client would not be able to send media to this address.
+
+
+Traditionally this was solved by using STUN. With this mechanism, the client
+first finds out its public IP address/port by querying a STUN server, then
+send sthis public address instead of its private address to the other 
+client. When both sides are using this mechanism, they can then send media 
+packets to these addresses, thereby creating a mapping in the NAT (also 
+called opening a "hole", hence this mechanism is also popularly called 
+"hole punching") and both can then communicate with each other.
+
+
+But this mechanism does not work in all cases, as will be explained below.
+
+
+
+\subsection hairpin Hairpinning behavior
+
+
+Hairpin is a behavior where a NAT device forwards packets from a host in
+internal network (lets call it host A) back to some other host (host B) in
+the same internal network, when it detects that the (public IP address)
+destination of the packet is actually a mapped IP address that was created
+for the internal host (host B). This is a desirable behavior of a NAT, 
+but unfortunately not all NAT devices support this.
+
+
+Lacking this behavior, two (internal) hosts behind the same NAT will not
+be able to communicate with each other if they exchange their public
+addresses (resolved by STUN above) to each other.
+
+
+
+\subsection symmetric Symmetric behavior
+
+
+NAT devices don't behave uniformly and people have been trying to classify
+their behavior into different classes. Traditionally NAT devices are
+classified into Full Cone, Restricted Cone, Port Restricted Cone, and 
+Symmetric types, according to <A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>
+section 5. A more recent method of classification, as explained by 
+<A HREF="http://www.ietf.org/rfc/rfc4787.txt">RFC 4787</A>, divides 
+the NAT behavioral types into two attributes: the mapping behavior 
+attribute and the filtering behavior attribute. Each attribute can be 
+one of three types: <i>Endpoint-Independent</i>, <i>Address-Dependent</i>,
+or <i>Address and Port-Dependent</i>. With this new classification method,
+a Symmetric NAT actually is an Address and Port-Dependent mapping NAT.
+
+
+Among these types, the Symmetric type is the hardest one to work with. 
+The problem is because the NAT allocates different mapping (of the same
+internal host) for the communication to the STUN server and the 
+communication to the other (external) hosts, so the IP address/port that
+is informed by one host to the other is meaningless for the recipient 
+since this is not the actual IP address/port mapping that the NAT device 
+creates. The result is when the recipient host tries to send a packet to 
+this address, the NAT device would drop the packet since it does not 
+recognize the sender of the packet as the "authorized" hosts to send 
+to this address.
+
+
+There are two solutions for this. The first, we could make the client 
+smarter by switching transmission of the media to the source address of 
+the media packets. This would work since normally clients uses a well 
+known trick called symmetric RTP, where they use one socket for both 
+transmitting and receiving RTP/media packets. We also use this 
+mechanism in PJMEDIA media transport. But this solution only works 
+if a client behind a symmetric NAT is not communicating with other 
+client behind either symmetric NAT or port-restricted NAT.
+
+
+The second solution is to use media relay, but as have been mentioned 
+above, relaying is costly, both in terms of bandwidth cost for service
+provider and additional latency introduced by relaying.
+
+
+
+\subsection binding_timeout Binding timeout
+
+When a NAT device creates a binding (a public-private IP address 
+mapping), it will associate a timer with it. The timer is used to 
+destroy the binding once there is no activity/traffic associated with 
+the binding. Because of this, a NAT aware application that wishes to 
+keep the binding open must periodically send outbound packets, 
+a mechanism known as keep-alive, or otherwise it will ultimately 
+loose the binding and unable to receive incoming packets from Internet.
+
+
+\section solutions The NAT traversal solutions
+
+
+\subsection stun Old STUN (RFC 3489)
+
+The original STUN (Simple Traversal of User Datagram Protocol (UDP) 
+Through Network Address Translators (NATs)) as defined by 
+<A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>
+(published in 2003, but the work was started as early as 2001) was 
+meant to be a standalone, standard-based solution for the NAT 
+connectivity problems above. It is equipped with NAT type detection 
+algoritm and methods to hole-punch the NAT in order to let traffic 
+to get through and has been proven to be quite successful in 
+traversing many types of NATs, hence it has gained a lot of popularity
+ as a simple and effective NAT traversal solution.
+
+But since then the smart people at IETF has realized that STUN alone 
+is not going to be enough. Besides its nature that STUN solution cannot 
+solve the symmetric-to-symmetric or port-restricted connection, 
+people have also discovered that NAT behavior can change for different 
+traffic (or for the same traffic overtime) hence it was concluded that 
+NAT type detection could produce unreliable results hence one should not 
+rely too much on it.
+
+Because of this, STUN has since moved its efforts to different strategy. 
+Instead of attempting to provide a standalone solution, it's now providing 
+a part solution and framework to build other (STUN based) protocols 
+on top of it, such as TURN and ICE.
+
+
+\subsection stunbis STUN/STUNbis (RFC 5389)
+
+The Session Traversal Utilities for NAT (STUN) is the further development 
+of the old STUN. While it still provides a mechanism for a client to 
+query its public/mapped address to a STUN server, it has deprecated 
+the use of NAT type detection, and now it serves as a framework to build 
+other protocols on top of it (such as TURN and ICE).
+
+
+\subsection midcom_turn Old TURN (draft-rosenberg-midcom-turn)
+
+Traversal Using Relay NAT (TURN), a standard-based effort started as early
+as in November 2001, was meant to be the complementary method for the 
+(old) STUN to complete the solution. The original idea was the host to use 
+STUN to detect the NAT type, and when it has found that the NAT type is 
+symmetric it would use TURN to relay the traffic. But as stated above, 
+this approach was deemed to be unreliable, and now the prefered way to use
+TURN (and it's a new TURN specification as well) is to combine it with ICE.
+
+
+\subsection turn TURN (draft-ietf-behave-turn)
+
+Traversal Using Relays around NAT (TURN) is the latest development of TURN. 
+While the protocol details have changed a lot, the objective is still 
+the same, that is to provide relaying control for the application. 
+As mentioned above, preferably TURN should be used with ICE since relaying 
+is costly in terms of both bandwidth and latency, hence it should be used 
+as the last resort.
+
+
+\subsection b2bua B2BUA approach
+
+A SIP Back to Back User Agents (B2BUA) is a SIP entity that sits in the 
+middle of SIP traffic and acts as SIP user agents on both call legs. 
+The primary motivations to have a B2BUA are to be able to provision 
+the call (e.g. billing, enforcing policy) and to help with NAT traversal 
+for the clients. Normally a B2BUA would be equipped with media relaying 
+or otherwise it wouldn't be very useful.
+
+Products that fall into this category include SIP Session Border 
+Controllers (SBC), and PBXs such as Asterisk are technically a B2BUA 
+as well.
+
+The benefit of B2BUA with regard to helping NAT traversal is it does not 
+require any modifications to the client to make it go through NATs. 
+And since basically it is a relay, it should be able to traverse 
+symmetric NAT successfully.
+
+However, since it is a relay, the usual relaying drawbacks apply, 
+namely the bandwidth and latency issue. More over, since a B2BUA acts 
+as user agent in either call-legs (i.e. it terminates the SIP 
+signaling/call on one leg, albeit it creates another call on the other 
+leg), it may also introduce serious issues with end-to-end SIP signaling.
+
+
+\subsection alg ALG approach
+
+Nowdays many NAT devices (such as consumer ADSL routers) are equipped 
+with intelligence to inspect and fix VoIP traffic in its effort to help 
+it with the NAT traversal. This feature is called Application Layer 
+Gateway (ALG) intelligence. The idea is since the NAT device knows about 
+the mapping, it might as well try to fix the application traffic so that 
+the traffic could better traverse the NAT. Some tricks that are 
+performed include for example replacing the private IP addresses/ports 
+in the SIP/SDP packet with the mapped public address/port of the host 
+that sends the packet.
+
+Despite many claims about its usefullness, in reality this has given us 
+more problems than the fix. Too many devices such as these break the 
+SIP signaling, and in more advanced case, ICE negotiation. Some 
+examples of bad situations that we have encountered in the past:
+
+ - NAT device alters the Via address/port fields in the SIP response 
+   message, making the response fail to pass SIP response verification 
+   as defined by SIP RFC.
+ - In other case, the modifications in the Via headers of the SIP 
+   response hides the important information from the SIP server, 
+   nameny the actual IP address/port of the client as seen by the SIP 
+   server.
+ - Modifications in the Contact URI of REGISTER request/response makes 
+   the client unable to detect it's registered binding.
+ - Modifications in the IP addresses/ports in SDP causes ICE 
+   negotiation to fail with ice-mismatch status.
+ - The complexity of the ALG processing in itself seems to have caused 
+   the device to behave erraticly with managing the address bindings 
+   (e.g. it creates a new binding for the second packet sent by the 
+   client, even when the previous packet was sent just second ago, or
+   it just sends inbound packet to the wrong host).
+
+
+Many man-months efforts have been spent just to troubleshoot issues 
+caused by these ALG (mal)functioning, and as it adds complexity to 
+the problem rather than solving it, in general we do not like this 
+approach at all and would prefer it to go away.
+
+
+\subsection upnp UPnP
+
+The Universal Plug and Play (UPnP) is a set of protocol specifications 
+to control network appliances and one of its specification is to 
+control NAT device. With this protocol, a client can instruct the 
+NAT device to open a port in the NAT's public side and use this port 
+for its communication. UPnP has gained popularity due to its 
+simplicity, and one can expect it to be available on majority of 
+NAT devices.
+
+The drawback of UPnP is since it uses multicast in its communication,
+it will only allow client to control one NAT device that is in the 
+same multicast domain. While this normally is not a problem in 
+household installations (where people normally only have one NAT 
+router), it will not work if the client is behind cascaded routers 
+installation. More over uPnP has serious issues with security due to 
+its lack of authentication, it's probably not the prefered solution 
+for organizations.
+
+\subsection other Other solutions
+
+Other solutions to NAT traversal includes:
+
+ - SOCKS, which supports UDP protocol since SOCKS5.
+
+
+
+\section ice ICE Solution - The Protocol that Works Harder
+
+A new protocol is being standardized (it's in Work Group Last Call/WGLC 
+stage at the time this article was written) by the IETF, called 
+Interactive Connectivity Establishment (ICE). ICE is the ultimate 
+weapon a client can have in its NAT traversal solution arsenals, 
+as it promises that if there is indeed one path for two clients 
+to communicate, then ICE will find this path. And if there are 
+more than one paths which the clients can communicate, ICE will 
+use the best/most efficient one.
+
+ICE works by combining several protocols (such as STUN and TURN) 
+altogether and offering several candidate paths for the communication, 
+thereby maximising the chance of success, but at the same time also 
+has the capability to prioritize the candidates, so that the more 
+expensive alternative (namely relay) will only be used as the last
+resort when else fails. ICE negotiation process involves several 
+stages:
+
+ - candidate gathering, where the client finds out all the possible 
+   addresses that it can use for the communication. It may find 
+   three types of candidates: host candidate to represent its 
+   physical NICs, server reflexive candidate for the address that 
+   has been resolved from STUN, and relay candidate for the address 
+   that the client has allocated from a TURN relay.
+ - prioritizing these candidates. Typically the relay candidate will
+   have the lowest priority to use since it's the most expensive.
+ - encoding these candidates, sending it to remote peer, and 
+   negotiating it with offer-answer.
+ - pairing the candidates, where it pairs every local candidates 
+   with every remote candidates that it receives from the remote peer.
+ - checking the connectivity for each candidate pairs.
+ - concluding the result. Since every possible path combinations are 
+   checked, if there is a path to communicate ICE will find it.
+
+
+There are many benetifs of ICE:
+
+ - it's standard based.
+ - it works where STUN works (and more)
+ - unlike standalone STUN solution, it solves the hairpinning issue, 
+   since it also offers host candidates.
+ - just as relaying solutions, it works with symmetric NATs. But unlike 
+   plain relaying, relay is only used as the last resort, thereby 
+   minimizing the bandwidth and latency issue of relaying.
+ - it offers a generic framework for offering and checking address 
+   candidates. While the ICE core standard only talks about using STUN 
+   and TURN, implementors can add more types of candidates in the ICE 
+   offer, for example UDP over TCP or HTTP relays, or even uPnP 
+   candidates, and this could be done transparently for the remote 
+   peer hence it's compatible and usable even when the remote peer 
+   does not support these.
+ - it also adds some kind of security particularly against DoS attacks, 
+   since media address must be acknowledged before it can be used.
+
+
+Having said that, ICE is a complex protocol to implement, making 
+interoperability an issue, and at this time of writing we don't see 
+many implementations of it yet. Fortunately, PJNATH has been one of 
+the first hence more mature ICE implementation, being first released
+on mid-2007, and we have been testing our implementation at 
+<A HREF="http://www.sipit.net">SIP Interoperability Test (SIPit)</A>
+events regularly, so hopefully we are one of the most stable as well.
+
+
+\section pjnath PJNATH - The building blocks for effective NAT traversal solution
+
+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:
+
+ - STUNbis implementation, providing both ready to use STUN-aware socket 
+   and framework to implement higher level STUN based protocols such as 
+   TURN and ICE.
+ - NAT type detection, useful for troubleshooting purposes.
+ - TURN implementation.
+ - ICE implementation.
+
+
+More protocols will be implemented in the future.
+
+Go back to \ref index.
+
+ */
Index: /pjproject/trunk/pjnath/docs/doc_samples.h
===================================================================
--- /pjproject/trunk/pjnath/docs/doc_samples.h	(revision 2642)
+++ /pjproject/trunk/pjnath/docs/doc_samples.h	(revision 2642)
@@ -0,0 +1,93 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2008-2009 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 
+ */
+
+
+/**
+@addtogroup samples_page
+
+Several samples that are included in the PJSIP distributions. The screenshots
+below were taken on a Windows machine, but the library is very portable and
+it is known to run on platforms such as Linux, MacOS X, Windows Mobile,
+Symbian, and so on.
+
+  - @ref ice_demo_sample\n
+    This sample demonstrates how to use \ref PJNATH_ICE_STREAM_TRANSPORT
+    <b>without</b> using signaling protocol such as <b>SIP</b>. It provides 
+    interactive user interface to create and manage the ICE sessions as well
+    as to exchange SDP with another ice_demo instance.\n\n
+    \image html ice_demo.jpg "ice_demo on WinXP"
+
+  - @ref turn_client_sample\n
+    This sample demonstrates how to use \ref PJNATH_TURN_SOCK
+    and also \ref PJNATH_STUN_SOCK. It provides interactive 
+    user interface to manage allocation, permissions, and
+    channel bindings.\n\n
+    \image html pjturn_client.jpg "pjturn_client on WinXP"
+
+  - TURN server sample\n
+    This is a simple sample TURN server application, which
+    we mainly use for testing (as back then there is no TURN
+    server available).\n
+    The source code for this application are in <tt><b>pjnath/src/pjturn-srv</b></tt>
+    directory.
+
+ */
+
+
+/**
+\page turn_client_sample pjturn-client, a sample TURN client
+
+This is a simple, interactive TURN client application, with the 
+following features:
+ - DNS SRV resolution
+ - TCP connection to TURN server
+ - Optional fingerprint
+
+This file is pjnath/src/pjturn-client/client_main.c.
+
+Screenshot on WinXP: \image html pjturn_client.jpg "pjturn_client on WinXP"
+
+\includelineno client_main.c.
+*/
+
+
+/**
+\page ice_demo_sample ice_demo, an interactive ICE endpoint
+
+This sample demonstrates how to use \ref PJNATH_ICE_STREAM_TRANSPORT
+<b>without</b> using signaling protocol such as SIP. It provides
+interactive user interface to create and manage the ICE sessions as well
+as to exchange SDP with another ice_demo instance.
+
+Features of the demo application:
+ - supports host, STUN, and TURN candidates
+ - disabling of host candidates
+ - DNS SRV resolution for STUN and TURN servers
+ - TCP connection to TURN server
+ - Optional use of fingerprint for TURN
+ - prints and parse SDP containing ICE infos
+ - exchange SDP with copy/paste
+
+This file is pjsip-apps/src/samples/icedemo.c
+
+Screenshot on WinXP: \image html ice_demo.jpg "ice_demo on WinXP"
+
+\includelineno icedemo.c.
+*/
+
Index: /pjproject/trunk/pjnath/docs/doc_stun.h
===================================================================
--- /pjproject/trunk/pjnath/docs/doc_stun.h	(revision 2642)
+++ /pjproject/trunk/pjnath/docs/doc_stun.h	(revision 2642)
@@ -0,0 +1,134 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2008-2009 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 
+ */
+
+
+/**
+@defgroup PJNATH_STUN STUN: Session Traversal Utilities for NAT
+@ingroup PJNATH
+@brief Open source STUN library
+ */
+
+/**
+@defgroup PJNATH_STUN_SOCK STUN-aware socket transport
+@brief STUN aware UDP socket transport
+@ingroup PJNATH_STUN
+ */
+
+
+/**
+@defgroup PJNATH_STUN_SESSION STUN session
+@brief STUN client and server session
+@ingroup PJNATH_STUN
+ */
+
+/**
+@defgroup PJNATH_STUN_BASE Base STUN objects
+@ingroup PJNATH_STUN
+@brief STUN data structures, objects, and configurations
+
+These section contains STUN base data structures as well as
+configurations. Among other things it contains STUN message
+representation and parsing, transactions, authentication
+framework, as well as compile-time and run-time configurations.
+*/
+
+
+/**
+@addtogroup PJNATH_STUN
+
+This module contains implementation of STUN library in PJNATH -
+the open source NAT helper containing STUN and ICE.
+
+\section stun_org_sec Library organizations
+
+The STUN part of PJNATH consists of the the following sections (see
+<b>Table of Contents</b> below).
+
+
+\section stun_using_sec Using the STUN transport
+
+The \ref PJNATH_STUN_SOCK is a ready to use object which provides 
+send and receive interface for communicating UDP packets as well as
+means to communicate with the STUN server and manage the STUN mapped
+address.
+
+Some features of the \ref PJNATH_STUN_SOCK:
+ - API to send and receive UDP packets,
+ - interface to query the STUN mapped address info, 
+ - multiplex STUN and non-STUN incoming packets and distinguish between
+   STUN responses that belong to internal requests with application data
+   (the application data may be STUN packets as well),
+ - resolution of the STUN server with DNS SRV query (if wanted), 
+ - maintaining STUN keep-alive, and 
+ - handle changes in STUN mapped address binding.
+
+Please see \ref PJNATH_STUN_SOCK for more information.
+
+
+\section stun_advanced_sec Advanced use of the STUN components
+
+The rest of the STUN part of the library provides lower level objects
+which can be used to build your own STUN based transport or
+protocols (officially called STUN usages). These will be explained 
+briefly below.
+
+
+\subsection stun_sess_sec The STUN session
+
+A STUN session is interactive information exchange between two STUN 
+endpoints that lasts for some period of time. It is typically started by
+an outgoing or incoming request, and consists of several requests, 
+responses, and indications. All requests and responses within the session
+typically share a same credential.
+
+The \ref PJNATH_STUN_SESSION is a transport-independent object to
+manage a client or server STUN session. It is one of the core object in
+PJNATH, and it is used by several higher level objects including the 
+\ref PJNATH_STUN_SOCK, \ref PJNATH_TURN_SESSION, and \ref PJNATH_ICE_SESSION.
+
+The \ref PJNATH_STUN_SESSION has the following features:
+   - transport independent
+   - authentication management
+   - static or dynamic credential
+   - client transaction management
+   - server transaction management
+
+For more information, including how to use it please see 
+\ref PJNATH_STUN_SESSION.
+
+
+\subsection stun_extending_sec Extending STUN to support other usages
+
+At present, the STUN subsystem in PJNATH supports STUN Binding, TURN, and
+ICE usages. If other usages are to be supported, typically you would need
+to add new STUN methods (and the corresponding request and response message
+types), attributes, and error codes to \ref PJNATH_STUN_MSG subsystem of
+PJNATH, as well as implementing the logic for the STUN usage.
+
+
+\section stunsamples_sec STUN samples
+
+The \ref turn_client_sample sample application also contains sample
+code to use \ref PJNATH_STUN_SOCK. 
+
+Also see <b>\ref samples_page</b> for other samples.
+
+
+ */
+
Index: /pjproject/trunk/pjnath/docs/doc_turn.h
===================================================================
--- /pjproject/trunk/pjnath/docs/doc_turn.h	(revision 2642)
+++ /pjproject/trunk/pjnath/docs/doc_turn.h	(revision 2642)
@@ -0,0 +1,164 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2008-2009 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 
+ */
+
+
+/**
+@defgroup PJNATH_TURN TURN: Traversal Using Relays around NAT
+@brief TURN protocol implementation
+@ingroup PJNATH
+
+\section turn_intro_sec Introduction to TURN
+
+When a direct communication path cannot be found, it is necessary to
+use the services of an intermediate host that acts as a relay for the
+packets.  This relay typically sits in the public Internet and relays
+packets between two hosts that both sit behind NATs.
+
+TURN allows a host behind a NAT (called the TURN client) to request that 
+another host (called the TURN server) act as a relay.  The client can 
+arrange for the server to relay packets to and from certain other hosts
+(called peers) and can control aspects of how the relaying is done.
+The client does this by obtaining an IP address and port on the
+server, called the relayed-transport-address.  When a peer sends a
+packet to the relayed-transport-address, the server relays the packet
+to the client.  When the client sends a data packet to the server,
+the server relays it to the appropriate peer using the relayed-
+transport-address as the source.
+
+
+\section turn_op_sec Overview of TURN operations
+
+<b>Discovering TURN server</b>.\n
+Client learns the IP address of the TURN
+server either through some privisioning or by querying DNS SRV records
+for TURN service for the specified domain. Client may use UDP or TCP (or
+TLS) to connect to the TURN server.
+
+<b>Authentication</b>.\n
+All TURN operations requires the use of authentication
+(it uses STUN long term autentication method), hence client must be
+configured with the correct credential to use the service.
+
+<b>Allocation</b>.\n
+Client creates one "relay port" (or called <b>relayed-transport-address</b>
+in TURN terminology) in the TURN server by sending TURN \a Allocate request,
+hence this process is called creating allocation. Once the allocation is 
+successful, client will be given the IP address and port of the "relay 
+port" in the Allocate response.
+
+<b>Sending data through the relay</b>.\n
+Once allocation has been created, client may send data to any remote 
+endpoints (called peers in TURN terminology) via the "relay port". It does 
+so by sending Send Indication to the TURN server, giving the peer address 
+in the indication message. But note that at this point peers are not allowed
+to send data towards the client (via the "relay port") before permission is 
+installed for that peer.
+
+<b>Creating permissions</b>.\n
+Permission needs to be created in the TURN server so that a peer can send 
+data to the client via the relay port (a peer in this case is identified by
+its IP address). Without this, when the TURN server receives data from the
+peer in the "relay port", it will drop this data.
+
+<b>Receiving data from peers</b>.\n
+Once permission has been installed for the peer, any data received by the 
+TURN server (from that peer) in the "relay port" will be relayed back to 
+client by using Data Indication.
+
+<b>Using ChannelData</b>.\n
+TURN provides optimized framing to the data by using ChannelData 
+packetization. The client activates this format by sending ChannelBind 
+request to the TURN server, which provides (channel) binding which maps a 
+particular peer address with a channel number. Data sent or received to/for
+this peer will then use ChannelData format instead of Send or Data 
+Indications.
+
+<b>Refreshing the allocation, permissions, and channel bindings</b>.\n
+Allocations, permissions, and channel bindings need to be refreshed
+periodically by client, or otherwise they will expire.
+
+<b>Destroying the allocation</b>.\n
+Once the "relay port" is no longer needed, client destroys the allocation
+by sending Refresh request with LIFETIME attribute set to zero.
+
+
+\section turn_org_sec Library organizations
+
+The TURN functionalities in PJNATH primarily consist of 
+\ref PJNATH_TURN_SOCK and \ref PJNATH_TURN_SESSION. Please see more
+below.
+
+
+\section turn_using_sec Using TURN transport
+
+The \ref PJNATH_TURN_SOCK is a ready to use object for relaying
+application data via a TURN server, by managing all the operations
+above.
+
+Among other things it provides the following features:
+ - resolution of the TURN server with DNS SRV
+ - interface to create allocation, permissions, and channel
+   bindings
+ - interface to send and receive packets through the relay
+ - provides callback to notify the application about incoming data
+ - managing the allocation, permissions, and channel bindings
+
+Please see \ref PJNATH_TURN_SOCK for more documentation about and
+on how to use this object.
+
+
+\section turn_owntransport_sec Creating custom TURN transport
+
+The \ref PJNATH_TURN_SESSION is a transport-independent object to
+manage a client TURN session. It contains the core logic for managing
+the TURN client session as listed in TURN operations above, but
+in transport-independent manner (i.e. it doesn't have a socket), so
+that developer can integrate TURN client functionality into existing
+framework that already has its own means to send and receive data,
+or to support new transport types to TURN, such as TLS.
+
+You can create your own (custom) TURN transport by wrapping this
+into your own object, and provide it with the means to send and
+receive packets.
+
+Please see \ref PJNATH_TURN_SESSION for more information.
+
+
+\section turn_samples_sec Samples
+
+The \ref turn_client_sample is a sample application to use the
+\ref PJNATH_TURN_SOCK. Also there is a sample TURN server in
+the distribution as well. 
+
+Also see <b>\ref samples_page</b> for other samples.
+
+ */
+
+
+/**
+ * @defgroup PJNATH_TURN_SOCK TURN client transport
+ * @brief Client transport utilizing TURN relay
+ * @ingroup PJNATH_TURN
+ */
+
+/**
+ * @defgroup PJNATH_TURN_SESSION TURN client session
+ * @brief Transport independent TURN client session
+ * @ingroup PJNATH_TURN
+ */
Index: /pjproject/trunk/pjnath/docs/doxygen.cfg
===================================================================
--- /pjproject/trunk/pjnath/docs/doxygen.cfg	(revision 2641)
+++ /pjproject/trunk/pjnath/docs/doxygen.cfg	(revision 2642)
@@ -347,5 +347,5 @@
 # with spaces.
 
-INPUT                  =  include/pjnath
+INPUT                  =  docs include/pjnath
 
 # If the value of the INPUT tag contains directories, you can use the 
@@ -385,5 +385,5 @@
 # the \include command).
 
-EXAMPLE_PATH           = .
+EXAMPLE_PATH           = ../pjsip-apps/src/samples src/pjturn-client
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
@@ -977,20 +977,4 @@
 DOTFILE_DIRS           = 
 
-# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width 
-# (in pixels) of the graphs generated by dot. If a graph becomes larger than 
-# this value, doxygen will try to truncate the graph, so that it fits within 
-# the specified constraint. Beware that most browsers cannot cope with very 
-# large images.
-
-MAX_DOT_GRAPH_WIDTH    = 1024
-
-# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height 
-# (in pixels) of the graphs generated by dot. If a graph becomes larger than 
-# this value, doxygen will try to truncate the graph, so that it fits within 
-# the specified constraint. Beware that most browsers cannot cope with very 
-# large images.
-
-MAX_DOT_GRAPH_HEIGHT   = 1024
-
 # If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will 
 # generate a legend page explaining the meaning of the various boxes and 
Index: /pjproject/trunk/pjnath/docs/footer.html
===================================================================
--- /pjproject/trunk/pjnath/docs/footer.html	(revision 2641)
+++ /pjproject/trunk/pjnath/docs/footer.html	(revision 2642)
@@ -1,2 +1,3 @@
+	</TD></TD></TABLE>
 <p>&nbsp;</p>
 <hr><center>
Index: /pjproject/trunk/pjnath/docs/header.html
===================================================================
--- /pjproject/trunk/pjnath/docs/header.html	(revision 2641)
+++ /pjproject/trunk/pjnath/docs/header.html	(revision 2642)
@@ -5,4 +5,5 @@
 </head><body>
 	<!--#include virtual="/header.html" -->
+	<TABLE border=0 width="90%"><TR><TD>
 	<p><A HREF="/">Home</A> --&gt; <A HREF="/docs.htm">Documentations</A> --&gt; <A HREF="/pjnath/docs/html/index.htm">PJNATH Reference</A></p>
 
Index: /pjproject/trunk/pjnath/include/pjnath/config.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/config.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/config.h	(revision 2642)
@@ -30,6 +30,7 @@
 
 /**
- * @defgroup PJNATH_CONFIG Configuration
+ * @defgroup PJNATH_CONFIG Compile-time configurations
  * @brief Various compile time settings
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
Index: /pjproject/trunk/pjnath/include/pjnath/errno.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/errno.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/errno.h	(revision 2642)
@@ -31,4 +31,5 @@
  * @defgroup PJNATH_ERROR NAT Helper Library Error Codes
  * @brief PJNATH specific error code constants
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
Index: /pjproject/trunk/pjnath/include/pjnath/ice_session.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/ice_session.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/ice_session.h	(revision 2642)
@@ -31,17 +31,9 @@
 #include <pj/timer.h>
 
-/**
- * @defgroup PJNATH_ICE Interactive Connectivity Establishment (ICE)
- * @brief Interactive Connectivity Establishment (ICE)
- */
-
-
 PJ_BEGIN_DECL
 
 
 /**
- * @defgroup PJNATH_ICE_SESSION ICE Session
- * @brief Transport Independent ICE Session
- * @ingroup PJNATH_ICE
+ * @addtogroup PJNATH_ICE_SESSION
  * @{
  *
@@ -205,14 +197,20 @@
 typedef struct pj_ice_msg_data
 {
+    /** Transport ID for this message */
     unsigned	transport_id;
+
+    /** Flag to indicate whether data.req contains data */
     pj_bool_t	has_req_data;
 
+    /** The data */
     union data {
+	/** Request data */
 	struct request_data {
-	    pj_ice_sess		    *ice;
-	    pj_ice_sess_checklist   *clist;
-	    unsigned		     ckid;
+	    pj_ice_sess		    *ice;   /**< ICE session	*/
+	    pj_ice_sess_checklist   *clist; /**< Checklist	*/
+	    unsigned		     ckid;  /**< Check ID	*/
 	} req;
     } data;
+
 } pj_ice_msg_data;
 
@@ -540,5 +538,5 @@
 typedef struct pj_ice_rx_check
 {
-    PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check);
+    PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check); /**< Standard list     */
 
     unsigned		 comp_id;	/**< Component ID.		*/
@@ -601,5 +599,5 @@
     pj_ice_sess_cand	 rcand[PJ_ICE_MAX_CAND];    /**< Array of cand.	    */
 
-    /* Array of transport datas */
+    /** Array of transport datas */
     pj_ice_msg_data	 tp_data[4];
 
@@ -613,5 +611,5 @@
     pj_ice_sess_checklist valid_list;		    /**< Valid list.	    */
     
-    /* Temporary buffer for misc stuffs to avoid using stack too much */
+    /** Temporary buffer for misc stuffs to avoid using stack too much */
     union {
     	char txt[128];
Index: /pjproject/trunk/pjnath/include/pjnath/ice_strans.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/ice_strans.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/ice_strans.h	(revision 2642)
@@ -38,7 +38,5 @@
 
 /**
- * @defgroup PJNATH_ICE_STREAM_TRANSPORT ICE Stream Transport
- * @brief Transport for media streams using ICE
- * @ingroup PJNATH_ICE
+ * @addtogroup PJNATH_ICE_STREAM_TRANSPORT
  * @{
  *
@@ -54,4 +52,64 @@
  * various candidates of the transport addresses.
  *
+ *
+ * \section ice_strans_using_sec Using the ICE stream transport
+ *
+ * The steps below describe how to use ICE session:
+ *
+ *  - initialize a #pj_ice_strans_cfg structure. This contains various 
+ *    settings for the ICE stream transport, and among other things contains
+ *    the STUN and TURN settings.\n\n
+ *  - create the instance with #pj_ice_strans_create(). Among other things,
+ *    the function needs the following arguments:
+ *	- the #pj_ice_strans_cfg structure for the main configurations
+ *	- number of components to be supported
+ *	- instance of #pj_ice_strans_cb structure to report callbacks to
+ *	  application.\n\n
+ *  - while the #pj_ice_strans_create() call completes immediately, the
+ *    initialization will be running in the background to gather the 
+ *    candidates (for example STUN and TURN candidates, if they are enabled
+ *    in the #pj_ice_strans_cfg setting). Application will be notified when
+ *    the initialization completes in the \a on_ice_complete callback of
+ *    the #pj_ice_strans_cb structure (the \a op argument of this callback
+ *    will be PJ_ICE_STRANS_OP_INIT).\n\n
+ *  - when media stream is to be started (for example, a call is to be 
+ *    started), create an ICE session by calling #pj_ice_strans_init_ice().\n\n
+ *  - the application now typically will need to communicate local ICE
+ *    information to remote host. It can achieve this by using the following
+ *    functions to query local ICE information:
+ *	- #pj_ice_strans_get_ufrag_pwd()
+ *	- #pj_ice_strans_enum_cands()
+ *	- #pj_ice_strans_get_def_cand()\n
+ *    The application may need to encode the above information as SDP.\n\n
+ *  - when the application receives remote ICE information (for example, from
+ *    the SDP received from remote), it can now start ICE negotiation, by
+ *    calling #pj_ice_strans_start_ice(). This function requires some
+ *    information about remote ICE agent such as remote ICE username fragment
+ *    and password as well as array of remote candidates.\n\n
+ *  - note that the PJNATH library does not work with SDP; application would
+ *    need to encode and parse the SDP itself.\n\n
+ *  - once ICE negotiation has been started, application will be notified
+ *    about the completion in the \a on_ice_complete() callback of the
+ *    #pj_ice_strans_cb.\n\n
+ *  - at any time, application may send or receive data. However the ICE
+ *    stream transport may not be able to send it depending on its current
+ *    state. Before ICE negotiation is started, the data will be sent using
+ *    default candidate of the component. After negotiation is completed,
+ *    data will be sent using the candidate from the successful/nominated
+ *    pair. The ICE stream transport may not be able to send data while 
+ *    negotiation is in progress.\n\n
+ *  - application sends data by using #pj_ice_strans_sendto(). Incoming
+ *    data will be reported in \a on_rx_data() callback of the
+ *    #pj_ice_strans_cb.\n\n
+ *  - once the media session has finished (e.g. user hangs up the call),
+ *    destroy the ICE session with #pj_ice_strans_stop_ice().\n\n
+ *  - at this point, application may destroy the ICE stream transport itself,
+ *    or let it run so that it can be reused to create other ICE session.
+ *    The benefit of letting the ICE stream transport alive (without any
+ *    session active) is to avoid delay with the initialization, howerver
+ *    keeping the transport alive means the transport needs to keep the
+ *    STUN binding open by using keep-alive and also TURN allocation alive,
+ *    and this will consume power which is an important issue for mobile
+ *    applications.\n\n
  */
 
Index: /pjproject/trunk/pjnath/include/pjnath/nat_detect.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/nat_detect.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/nat_detect.h	(revision 2642)
@@ -34,4 +34,5 @@
  * @defgroup PJNATH_NAT_DETECT NAT Classification/Detection Tool
  * @brief NAT Classification/Detection Tool
+ * @ingroup PJNATH
  * @{
  *
Index: /pjproject/trunk/pjnath/include/pjnath/stun_auth.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/stun_auth.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/stun_auth.h	(revision 2642)
@@ -36,5 +36,5 @@
  * @defgroup PJNATH_STUN_AUTH STUN Authentication
  * @brief STUN authentication helper
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
Index: /pjproject/trunk/pjnath/include/pjnath/stun_config.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/stun_config.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/stun_config.h	(revision 2642)
@@ -39,5 +39,5 @@
  * @defgroup PJNATH_STUN_CONFIG STUN Config
  * @brief STUN config
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @{
  */
Index: /pjproject/trunk/pjnath/include/pjnath/stun_msg.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/stun_msg.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/stun_msg.h	(revision 2642)
@@ -36,5 +36,5 @@
 /**
  * @defgroup PJNATH_STUN_MSG STUN Message Representation and Parsing
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @brief Low-level representation and parsing of STUN messages.
  * @{
Index: /pjproject/trunk/pjnath/include/pjnath/stun_session.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/stun_session.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/stun_session.h	(revision 2642)
@@ -38,8 +38,128 @@
 /* **************************************************************************/
 /**
- * @defgroup PJNATH_STUN_SESSION STUN Client/Server Session
- * @brief STUN client and server session
- * @ingroup PJNATH_STUN
+ * @addtogroup PJNATH_STUN_SESSION
  * @{
+ *
+ * This is is a transport-independent object to manage a client or server 
+ * STUN session. It has the following features:
+ * 
+ *  - <b>transport independent</b>:\n
+ *    the object does not have it's own socket, but rather it provides
+ *    functions and callbacks to send and receive packets. This way the
+ *    object can be used by different transport types (e.g. UDP, TCP, 
+ *    TLS, etc.) as well as better integration to application which
+ *    already has its own means to send and receive packets.
+ * 
+ *  - <b>authentication management</b>:\n
+ *    the object manages STUN authentication throughout the lifetime of
+ *    the session. For client sessions, once it's given a credential to
+ *    authenticate itself with the server, the object will automatically
+ *    add authentication info (the MESSAGE-INTEGRITY) to the request as
+ *    well as authenticate the response. It will also handle long-term 
+ *    authentication challenges, including handling of nonce expiration,
+ *    and retry the request automatically. For server sessions, it can 
+ *    be configured to authenticate incoming requests automatically.
+ *  
+ *  - <b>static or dynamic credential</b>:\n
+ *    application may specify static or dynamic credential to be used by
+ *    the STUN session. Static credential means a static combination of
+ *    username and password (and these cannot change during the session
+ *    duration), while dynamic credential provides callback to ask the
+ *    application about which username/password to use everytime
+ *    authentication is about to be performed.
+ *    
+ *  - <b>client transaction management</b>:\n
+ *    outgoing requests may be sent with a STUN transaction for reliability,
+ *    and the object will manage the transaction internally (including
+ *    performing retransmissions). Application will be notified about the
+ *    result of the request when the response arrives (or the transaction
+ *    times out). When the request is challenged with authentication, the
+ *    object will retry the request with new authentication info, and 
+ *    application will be notified about the final result of this request.
+ * 
+ *  - <b>server transaction management</b>:\n
+ *    application may ask response to incoming requests to be cached by
+ *    the object, and in this case the object will check for cached
+ *    response everytime request is received. The cached response will be
+ *    deleted once a timer expires.
+ *
+ * \section using_stun_sess_sec Using the STUN session
+ *
+ * The following steps describes how to use the STUN session:
+ *
+ *  - <b>create the object configuration</b>:\n
+ *    The #pj_stun_config contains the configuration to create the STUN
+ *    session, such as the timer heap to register internal timers and
+ *    various STUN timeout values. You can initialize this structure by
+ *    calling #pj_stun_config_init()
+ *
+ *  - <b>create the STUN session</b>:\n
+ *    by calling #pj_stun_session_create(). Among other things, this
+ *    function requires the instance of #pj_stun_config and also 
+ *    #pj_stun_session_cb structure which stores callbacks to send
+ *    outgoing packets as well as to notify application about incoming
+ *    STUN requests, responses, and indicates and other events.
+ *
+ *  - <b>configure credential:</b>\n
+ *    if authentication is required for the session, configure the
+ *    credential with #pj_stun_session_set_credential()
+ *
+ *  - <b>configuring other settings:</b>\n
+ *    several APIs are provided to configure the behavior of the STUN
+ *    session (for example, to set the SOFTWARE attribute value, controls
+ *    the logging behavior, fine tune the mutex locking, etc.). Please see
+ *    the API reference for more info.
+ *
+ *  - <b>creating outgoing STUN requests or indications:</b>\n
+ *    create the STUN message by using #pj_stun_session_create_req() or
+ *    #pj_stun_session_create_ind(). This will create a transmit data
+ *    buffer containing a blank STUN request or indication. You will then
+ *    typically need to add STUN attributes that are relevant to the
+ *    request or indication, but note that some default attributes will
+ *    be added by the session later when the message is sent (such as
+ *    SOFTWARE attribute and attributes related to authentication).
+ *    The message is now ready to be sent.
+ *
+ *  - <b>sending outgoing message:</b>\n
+ *    use #pj_stun_session_send_msg() to send outgoing STUN messages (this
+ *    includes STUN requests, indications, and responses). The function has
+ *    options whether to retransmit the request (for non reliable transports)
+ *    or to cache the response if we're sending response. This function in 
+ *    turn will call the \a on_send_msg() callback of #pj_stun_session_cb 
+ *    to request the application to send the packet.
+ *
+ *  - <b>handling incoming packet:</b>\n
+ *    call #pj_stun_session_on_rx_pkt() everytime the application receives
+ *    a STUN packet. This function will decode the packet and process the
+ *    packet according to the message, and normally this will cause one
+ *    of the callback in the #pj_stun_session_cb to be called to notify
+ *    the application about the event.
+ *
+ *  - <b>handling incoming requests:</b>\n
+ *    incoming requests are notified to application in the \a on_rx_request
+ *    callback of the #pj_stun_session_cb. If authentication is enabled in
+ *    the session, the application will only receive this callback after
+ *    the incoming request has been authenticated (if the authentication
+ *    fails, the session would respond automatically with 401 error and
+ *    the callback will not be called). Application now must create and
+ *    send response for this request.
+ *
+ *  - <b>creating and sending response:</b>\n
+ *    create the STUN response with #pj_stun_session_create_res(). This will
+ *    create a transmit data buffer containing a blank STUN response. You 
+ *    will then typically need to add STUN attributes that are relevant to
+ *    the response, but note that some default attributes will
+ *    be added by the session later when the message is sent (such as
+ *    SOFTWARE attribute and attributes related to authentication).
+ *    The message is now ready to be sent. Use #pj_stun_session_send_msg()
+ *    (as explained above) to send the response.
+ *
+ *  - <b>convenient way to send response:</b>\n
+ *    the #pj_stun_session_respond() is provided as a convenient way to
+ *    create and send simple STUN responses, such as error responses.
+ *    
+ *  - <b>destroying the session:</b>\n
+ *    once the session is done, use #pj_stun_session_destroy() to destroy
+ *    the session.
  */
 
Index: /pjproject/trunk/pjnath/include/pjnath/stun_sock.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/stun_sock.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/stun_sock.h	(revision 2642)
@@ -35,14 +35,22 @@
 
 /**
- * @defgroup PJNATH_STUN_SOCK STUN aware socket transport
- * @brief STUN aware socket transport
- * @ingroup PJNATH_STUN
+ * @addtogroup PJNATH_STUN_SOCK
  * @{
  *
  * The STUN transport provides asynchronous UDP like socket transport
- * with the additional capability to query the publicly mapped transport
- * address (using STUN resolution), to refresh the NAT binding, and to
- * demultiplex internal STUN messages from application data (the 
- * application data may be a STUN message as well).
+ * with the additional STUN capability. It has the following features:
+ *
+ *  - API to send and receive UDP packets
+ *
+ *  - multiplex STUN and non-STUN incoming packets and distinguish between
+ *    STUN responses that belong to internal requests with application data
+ *    (the application data may be STUN packets as well)
+ *
+ *  - DNS SRV resolution to the STUN server (if wanted), along with fallback
+ *    to DNS A resolution if SRV record is not found.
+ *
+ *  - STUN keep-alive maintenance, and handle changes to the mapped address
+ *    (when the NAT binding changes)
+ *
  */
 
@@ -276,5 +284,5 @@
  * @param p_sock	Pointer to receive the created transport instance.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
@@ -328,5 +336,5 @@
  * @param sock		The STUN transport socket.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
@@ -341,5 +349,5 @@
  * @param user_data	Arbitrary data.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
@@ -353,5 +361,5 @@
  * @param stun_sock	The STUN transport instance.
  *
- * @restun		The user/application data.
+ * @return		The user/application data.
  */
 PJ_DECL(void*) pj_stun_sock_get_user_data(pj_stun_sock *stun_sock);
@@ -365,5 +373,5 @@
  * @param info		Pointer to be filled with STUN transport info.
  *
- * @restun		PJ_SUCCESS if the operation has been successful,
+ * @return		PJ_SUCCESS if the operation has been successful,
  *			or the appropriate error code on failure.
  */
@@ -377,5 +385,5 @@
  *
  * @param stun_sock	The STUN transport instance.
- * @param op_key	Optional send key for sending the packet down to
+ * @param send_key	Optional send key for sending the packet down to
  *			the ioqueue. This value will be given back to
  *			\a on_data_sent() callback
Index: /pjproject/trunk/pjnath/include/pjnath/stun_transaction.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/stun_transaction.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/stun_transaction.h	(revision 2642)
@@ -37,5 +37,5 @@
  * @defgroup PJNATH_STUN_TRANSACTION STUN Client Transaction
  * @brief STUN client transaction
- * @ingroup PJNATH_STUN
+ * @ingroup PJNATH_STUN_BASE
  * @{
  *
Index: /pjproject/trunk/pjnath/include/pjnath/turn_session.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/turn_session.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/turn_session.h	(revision 2642)
@@ -31,23 +31,97 @@
 PJ_BEGIN_DECL
 
-/**
- * @defgroup PJNATH_TURN TURN Client Library
- */
-
 
 /* **************************************************************************/
 /**
- * @defgroup PJNATH_TURN_SESSION Transport independent TURN client session
- * @brief Transport independent TURN client session
- * @ingroup PJNATH_TURN
- * @{
- *
- * This module describes the transport independent TURN client session. This
- * interface is provided for implementors of a TURN client transport, and
- * application usually will want to use \ref PJNATH_TURN_SOCK instead.
- *
- * The transport independent TURN client session is created to facilitate
- * the creation of different types of transports between the client and the
- * TURN server.
+@addtogroup PJNATH_TURN_SESSION
+@{
+
+The \ref PJNATH_TURN_SESSION is a transport-independent object to
+manage a client TURN session. It contains the core logic for manage
+the TURN client session as listed in \ref turn_op_sec, but
+in transport-independent manner (i.e. it doesn't have a socket), so
+that developer can integrate TURN client functionality into existing
+framework that already has its own means to send and receive data,
+or to support new transport types to TURN, such as TLS.
+
+
+\section turn_sess_using_sec Using the TURN session
+
+These steps describes how to use the TURN session:
+
+ - <b>Creating the session</b>:\n
+   use #pj_turn_session_create() to create the session. 
+
+ - <b>Configuring credential</b>:\n
+   all TURN operations requires the use of authentication (it uses STUN 
+   long term autentication method). Use #pj_turn_session_set_credential()
+   to configure the TURN credential to be used by the session.
+
+ - <b>Configuring server</b>:\n
+   application must call #pj_turn_session_set_server() before it can send
+   Allocate request (with pj_turn_session_alloc()). This function will
+   resolve the TURN server using DNS SRV resolution if the \a resolver
+   is set. The server resolution process will complete asynchronously,
+   and application will be notified in \a on_state() callback of the 
+   #pj_turn_session_cb structurewith the session state set to 
+   PJ_TURN_STATE_RESOLVED.
+
+ - <b>Creating allocation</b>:\n
+   create one "relay port" (or called <b>relayed-transport-address</b>
+   in TURN terminology) in the TURN server by using #pj_turn_session_alloc().
+   This will send Allocate request to the server. This function will complete
+   immediately, and application will be notified about the allocation
+   result in the \a on_state() callback of the #pj_turn_session_cb structure.
+
+ - <b>Getting the allocation result</b>:\n
+   if allocation is successful, the session state will progress to
+   \a PJ_TURN_STATE_READY, otherwise the state will be 
+   \a PJ_TURN_STATE_DEALLOCATED or higher. Session state progression is
+   reported in the \a on_state() callback of the #pj_turn_session_cb 
+   structure. On successful allocation, application may retrieve the
+   allocation info by calling #pj_turn_session_get_info().
+
+ - <b>Sending data through the relay</b>.\n
+   Once allocation has been created, client may send data to any remote 
+   endpoints (called peers in TURN terminology) via the "relay port". It does
+   so by calling #pj_turn_session_sendto(), giving the peer address 
+   in the function argument. But note that at this point peers are not allowed
+   to send data towards the client (via the "relay port") before permission is
+   installed for that peer.
+
+ - <b>Creating permissions</b>.\n
+   Permission needs to be created in the TURN server so that a peer can send 
+   data to the client via the relay port (a peer in this case is identified by
+   its IP address). Without this, when the TURN server receives data from the
+   peer in the "relay port", it will drop this data. Create the permission by
+   calling #pj_turn_session_set_perm(), specifying the peer IP address in the
+   argument (the port part of the address is ignored). More than one IP 
+   addresses may be specified.
+
+ - <b>Receiving data from peers</b>.\n
+   Once permission has been installed for the peer, any data received by the 
+   TURN server (from that peer) in the "relay port" will be relayed back to 
+   client by the server, and application will be notified via \a on_rx_data
+   callback of the #pj_turn_session_cb.
+
+ - <b>Using ChannelData</b>.\n
+   TURN provides optimized framing to the data by using ChannelData 
+   packetization. The client activates this format for the specified peer by
+   calling #pj_turn_session_bind_channel(). Data sent or received to/for
+   this peer will then use ChannelData format instead of Send or Data 
+   Indications.
+
+ - <b>Refreshing the allocation, permissions, and channel bindings</b>.\n
+   Allocations, permissions, and channel bindings will be refreshed by the
+   session automatically when they about to expire.
+
+ - <b>Destroying the allocation</b>.\n
+   Once the "relay port" is no longer needed, client destroys the allocation
+   by calling #pj_turn_session_shutdown(). This function will return
+   immediately, and application will be notified about the deallocation
+   result in the \a on_state() callback of the #pj_turn_session_cb structure.
+   Once the state has reached PJ_TURN_STATE_DESTROYING, application must
+   assume that the session will be destroyed shortly after.
+
  */
 
Index: /pjproject/trunk/pjnath/include/pjnath/turn_sock.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/turn_sock.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/turn_sock.h	(revision 2642)
@@ -33,15 +33,24 @@
 /* **************************************************************************/
 /**
- * @defgroup PJNATH_TURN_SOCK TURN client transport
- * @brief Client transport utilizing TURN relay
- * @ingroup PJNATH_TURN
- * @{
- *
- * The TURN relay client transport can be used to relay data from the client
- * to peer via a TURN relay. The application establishes TURN connection to
- * the TURN server using UDP or TCP as the transport, then creates a relay
- * address in the TURN server to be advertised to remote peer(s) as the 
- * transport address. When application sends data to a remote address via
- * this transport, the data will be sent via the TURN relay, and vice versa.
+@addtogroup PJNATH_TURN_SOCK
+@{
+
+This is a ready to use object for relaying application data via a TURN server,
+by managing all the operations in \ref turn_op_sec.
+
+\section turnsock_using_sec Using TURN transport
+
+This object provides a thin wrapper to the \ref PJNATH_TURN_SESSION, hence the
+API is very much the same (apart from the obvious difference in the names).
+Please see \ref PJNATH_TURN_SESSION for the documentation on how to use the
+session.
+
+\section turnsock_samples_sec Samples
+
+The \ref turn_client_sample is a sample application to use the
+\ref PJNATH_TURN_SOCK.
+
+Also see <b>\ref samples_page</b> for other samples.
+
  */
 
@@ -207,4 +216,19 @@
 
 /**
+ * Configure the SOFTWARE name to be sent in all STUN requests by the
+ * TURN session.
+ *
+ * @param turn_sock	The TURN transport instance.
+ * @param sw	    Software name string. If this argument is NULL or
+ *		    empty, the session will not include SOFTWARE attribute
+ *		    in STUN requests and responses.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_turn_sock_set_software_name(pj_turn_sock *turn_sock,
+						    const pj_str_t *sw);
+
+
+/**
  * Allocate a relay address/resource in the TURN server. This function
  * will resolve the TURN server using DNS SRV (if desired) and send TURN
Index: /pjproject/trunk/pjnath/include/pjnath/types.h
===================================================================
--- /pjproject/trunk/pjnath/include/pjnath/types.h	(revision 2641)
+++ /pjproject/trunk/pjnath/include/pjnath/types.h	(revision 2642)
@@ -73,229 +73,4 @@
  */
 
-/* Doxygen documentation below: */
-
-/**
-
-@mainpage PJNATH - Open Source ICE, STUN, and TURN Library
-
-\n
-This is the documentation of PJNATH, an Open Source library providing
-NAT traversal helper functionalities by using standard based protocols
-such as STUN, TURN, and ICE.
-
-\n
-\n
-
-\section lib_comps Library Components
-
-\subsection comp_stun STUN
-
-Session Traversal Utilities (STUN, or previously known as Simple 
-Traversal of User Datagram Protocol (UDP) Through Network Address 
-Translators (NAT)s), is a lightweight protocol that serves as a tool for
-application protocols in dealing with NAT traversal. It allows a client
-to determine the IP address and port allocated to them by a NAT and to 
-keep NAT bindings open.
-
-This version of PJNATH implements the following STUN RFC:
-- <A HREF="http://www.ietf.org/rfc/rfc5389.txt"><B>RFC 5389</b></A>: 
-    Session Traversal Utilities for (NAT) (STUN),
-
-
-\subsection comp_turn TURN
-
-Traversal Using Relays around NAT (TURN) allows the host to control the
-operation of the relay and to exchange packets with its peers using the relay.
-
-Features:
- - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-13.txt">
-   <B>draft-ietf-behave-turn-13</B></A>: Obtaining Relay Addresses 
-   from Simple Traversal Underneath NAT (STUN)
- - DNS SRV resolution
- - Fallback to DNS A resolution if SRV record is not found
- - UDP and TCP connection to TURN server
- - automatic management of allocation refresh
-
-
-
-\subsection comp_ice ICE
-
-Interactive Connectivity Establishment (ICE) is a standard based 
-methodology for traversing Network Address Translator (NAT). This
-implementation is aimed to provide a usable and generic ICE transports
-for different types of application, including but not limited to
-the usage of ICE in SIP/SDP offer/answer.
-
-
-This version of PJNATH implements the following ICE draft:
- - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-19.txt">
-   <B>draft-ietf-mmusic-ice-19.txt</B></A> draft. The PJNATH ICE
-
-
-\subsection comp_natck NAT Classification Utility
-
-The PJNATH library also provides NAT classification utility as 
-described in <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
-
-\section lib_org Library Organization
-
-The PJNATH library consists of many components with each providing
-specific functionality that may or may not be of the interests of 
-applications (or application developers). This section attempts to 
-give brief overview on the components provided by PJNATH.
-
-The PJNATH components from the highest layer to the lower layer are
-as follows.
-
-
-\n
-
-\subsection user_comp High-level Transport Objects
-
-PJNATH library provides some high-level objects that may be used
-by applications:
-
-
-\subsubsection stun_sock STUN Transport
-
-The \ref PJNATH_STUN_SOCK provides asynchronous UDP like socket transport
-with the additional capability to query the publicly mapped transport
-address (using STUN resolution), to refresh the NAT binding, and to
-demultiplex internal STUN messages from application data (the 
-application data may be a STUN message as well).
-
-
-\subsubsection turn_sock TURN Client Transport
-
-The \ref PJNATH_TURN_SOCK may be used by the application to send and
-receive data via TURN server. For more information please see the
-documentation of \ref PJNATH_TURN_SOCK.
-
-
-\subsubsection ice_strans ICE Stream Transport
-
-The \ref PJNATH_ICE_STREAM_TRANSPORT provides transport interface to
-send and receive data through connection that is negotiated
-with ICE protocol. The \ref PJNATH_ICE_STREAM_TRANSPORT naturally 
-contains both STUN Transport and \ref PJNATH_TURN_SOCK.
-
-The \ref PJNATH_ICE_STREAM_TRANSPORT interface is suitable for both
-SIP or non-SIP use. For SIP use, application may prefer to use the
-ICE media transport in PJMEDIA instead where it has been integrated
-with the SDP offer and answer mechanism.
-
-
-\subsubsection natck NAT Classification Utility
-
-PJNATH also provides \a PJNATH_NAT_DETECT to assist troubleshooting
-of problems related to NAT traversal.
-
-
-
-\n
-
-
-\subsection sessions Transport Independent Sessions Layer
-
-Right below the high level transports objects are the transport
-independent sessions. These sessions don't have access to sockets,
-so higher level objects (such as transports) must give incoming
-packets to the sessions and provide callback to be called by
-sessions to send outgoing packets.
-
-
-\subsubsection ice_sess ICE Session
-
-The \ref PJNATH_ICE_SESSION is used by the \ref PJNATH_ICE_STREAM_TRANSPORT
-and contains the actual logic of the ICE negotiation.
-
-
-\subsubsection turn_sess TURN Session
-
-The \ref PJNATH_TURN_SESSION is used by the \ref PJNATH_TURN_SOCK
-and it contains TURN protocol logic. Implementors may implement
-other types of TURN client connection (such as TURN TLS client)
-by utilizing this session.
-
-
-\subsubsection stun_sess STUN Session
-
-The \ref PJNATH_STUN_SESSION manages STUN message exchange between
-a client and server (or vice versa). It manages \ref PJNATH_STUN_TRANSACTION
-for sending or receiving requests and \ref PJNATH_STUN_AUTH for both
-both incoming and outgoing STUN messages. 
-
-The \ref PJNATH_STUN_SESSION is naturally used by the \ref PJNATH_TURN_SESSION
-and \ref PJNATH_ICE_SESSION
-
-
-\n
-
-\subsection stun_tsx STUN Transaction Layer
-
-The \ref PJNATH_STUN_TRANSACTION is a thin layer to manage retransmission
-of STUN requests.
-
-
-\n
-
-
-\subsection stun_msg STUN Messaging Layer
-
-At the very bottom of the PJNATH components is the \ref PJNATH_STUN_MSG
-layer. The API contains various representation of STUN messaging components
-and it provides API to encode and decode STUN messages.
-
-
-
-\n
-\n
-
-\section class_dia Class Diagram
-
-
-The following class diagram shows the interactions between objects in
-PJNATH:
-
-\image html UML-class-diagram.png "Class Diagram"
-\image latex UML-class-diagram.png "Class Diagram"
-
-
-
-\n
-\n
-
-\section samples Sample Applications
-
-
-Some sample applications have been provided with PJNATH, and it's available
-under <tt>pjnath/src</tt> directory:
-
-   - <b>pjturn-client</b>: this is a stand-alone, console based TURN client
-     application to be used as a demonstration for PJNATH TURN client 
-     transport API and for simple testing against TURN server implementations.
-     The client supports both UDP and TCP connection to the TURN server.
-
-   - <b>pjturn-srv</b>: this is a simple TURN server to be used for testing
-     purposes. It supports both UDP and TCP connections to the clients.
-
-
-*/
-
-/**
- * @defgroup PJNATH_STUN STUN Library
- * @brief Open source STUN library
- *
- * This module contains implementation of STUN library in PJNATH -
- * the open source NAT helper containing STUN and ICE.
- */
-
 #endif	/* __PJNATH_TYPES_H__ */
 
Index: /pjproject/trunk/pjnath/src/pjnath/turn_sock.c
===================================================================
--- /pjproject/trunk/pjnath/src/pjnath/turn_sock.c	(revision 2641)
+++ /pjproject/trunk/pjnath/src/pjnath/turn_sock.c	(revision 2642)
@@ -340,4 +340,13 @@
 
 /*
+ * Set software name
+ */
+PJ_DEF(pj_status_t) pj_turn_sock_set_software_name( pj_turn_sock *turn_sock,
+						    const pj_str_t *sw)
+{
+    return pj_turn_session_set_software_name(turn_sock->sess, sw);
+}
+
+/*
  * Initialize.
  */
