Added stunc.1 manpage, included sip-dig.1 manpage to the distribution.

darcs-hash:20060711230623-7659e-f6cb6decf783abec5603a21947d733898937339b.gz

Makefile.am

@@ -26,7 +26,8 @@ dist_m4_DATA = 	m4/sac-general.m4 m4/sac-su.m4
 EXTRA_DIST += 	m4/sac-su2.m4 m4/sac-tport.m4 m4/sac-openssl.m4
 
 dist_man_MANS = man/man1/sip-date.1 man/man1/sip-options.1 \
-		man/man1/localinfo.1 man/man1/addrinfo.1 
+		man/man1/localinfo.1 man/man1/addrinfo.1 \
+		man/man1/stunc.1 man/man1/sip-dig.1
 
 manpages $(MANS):
 	-mkdir -p $(srcdir)/man $(srcdir)/man/man1 2> /dev/null

libsofia-sip-ua/stun/stunc.c

@@ -23,7 +23,7 @@
  */
 
 /**
- * @file stunc.c STUN test client
+ * STUN test client
  * 
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>
  * @author Martti Mela <Martti.Mela@nokia.com>
@@ -32,6 +32,90 @@
  * @date Created: Thu Jul 24 17:21:00 2003 ppessi
  */
 
+/**@page stunc STUN test client.
+ * 
+ * @section stunc_synopsis Synopsis
+ * <tt>stunc [OPTIONS] \<stun-server-address\></tt>
+ *
+ * @section stunc_description Description
+ * The @em stunc utility can be used to gather information about possible
+ * NAT devices that are located between the client and STUN server. 
+ *
+ * @em stunc can provide the following information: the IP address and
+ * port as seen by the STUN server, detecting presence of NATs, and
+ * hints on the type of address translation done. It should be noted
+ * that the results of NAT type and life-time detection should be
+ * considered as hints. There is no guarantee that NAT(s) will handle
+ * future packets in the same way.
+ *
+ * @section stunc_options Command Line Options
+ * The @em stunc utility accepts following command line options:
+ *
+ * <dl>
+ *
+ * <dt>-b</dt>
+ * <dd>Perform a STUN binding discovery. @em stunc will report the
+ * client transport address (IP:port) as seen by the STUN server. In
+ * the presence of NATs, this address is allocated by the NAT closest
+ * to the STUN server.
+ * </dd>
+ *
+ * <dt>-l</dt>
+ * <dd>Perform a STUN binding life-time check.
+ * </dd>
+ *
+ * <dt>-n</dt>
+ * <dd>Perform a STUN binding type check. Notice that the results
+ * are only hints. Nondeterministic behaviour, resource exhaustion,
+ * or reboots of network elements can cause changes in NAT behaviour
+ * between successive runs of stunc.
+ * </dd>
+ *
+ * <dt>-r</dt>
+ * <dd>Randomize the local port. Otherwise @em stunc let's the
+ * operating system select a free port.
+ * </dd>
+ *
+ * <dt>-s</dt>
+ * <dd>Request a shared-secret over TLS. Tests whether the STUN server
+ * supports the shared-secret mechanism (needed to protect message 
+ * integrity). Can be combined with @em -b, @em -l and @em -n.
+ * </dd>
+ *
+ * </dl>
+ *
+ * @section stunc_return Return Codes
+ * <table>
+ * <tr><td>0</td><td>when successful</td></tr>
+ * <tr><td>1</td><td>when any errors detected</td></tr>
+ * </table>
+ *
+ * @section stunc_examples Examples
+ *
+ * Discover the NAT binding, use a random local port:
+ * @code
+ * $ stunc stunserver.org -b -r
+ * @endcode
+ *
+ * @section stunc_environment Environment
+ * #STUN_DEBUG
+ * 
+ * @section stunc_bugs Reporting Bugs
+ * Report bugs to <sofia-sip-devel@lists.sourceforge.net>.
+ *
+ * @section stunc_author Authors
+ * - Pekka Pessi <pekka -dot pessi -at- nokia -dot- com>
+ * - Martti Mela <martti -dot mela -at- nokia -dot- com>
+ * - Kai Vehmanen <kai -dot vehmanen -at- nokia -dot- com>
+ *
+ * @section stunc_copyright Copyright
+ * Copyright (C) 2005,2006 Nokia Corporation.
+ *
+ * This program is free software; see the source for copying conditions.
+ * There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE.
+ */
+
 #include "config.h" 
 
 #include <stdio.h>

utils/Doxyfile

@@ -4,6 +4,7 @@ OUTPUT_DIRECTORY     = ../man
 INPUT 		     = . 
 INPUT               += ../libsofia-sip-ua/su/localinfo.c
 INPUT               += ../libsofia-sip-ua/su/addrinfo.c
+INPUT               += ../libsofia-sip-ua/stun/stunc.c
 
 @INCLUDE = ../libsofia-sip-ua/docs/Doxyfile.aliases
 

utils/sip-dig.c

@@ -22,8 +22,7 @@
  *
  */
 
-/**@file sip-dig.c Use sresolv library to resolve a SIP or SIPS URI
- *
+/**
  * This is an example program for @b sresolv library in synchronous mode.
  *
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>