su: updated documentation

darcs-hash:20070627094304-65a35-adea6070f058da87a281c983f8b7598620ccaad4.gz

libsofia-sip-ua/su/sofia-sip/su.h

@@ -274,7 +274,9 @@ SOFIAPUBFUN int su_close(su_socket_t s);
 /** Control socket. */
 SOFIAPUBFUN int su_ioctl(su_socket_t s, int request, ...);
 
-/** Checks if the @a errcode indicates that the socket call failed because
+/**Check for in-progress error codes.
+ * 
+ * Checks if the @a errcode indicates that the socket call failed because
  * it would have blocked.
  *
  * Defined as macro with POSIX sockets.

libsofia-sip-ua/su/su.c

@@ -53,26 +53,55 @@
 int su_socket_close_on_exec = 0;
 int su_socket_blocking = 0;
 
-/** Create an endpoint for communication. */
+/** Create a socket endpoint for communication.
+ *
+ * @param af addressing family 
+ * @param socktype socket type 
+ * @param proto protocol number specific to the addressing family
+ *
+ * The newly created socket is nonblocking unless global variable
+ * su_socket_blocking is set to true. 
+ *
+ * Also, the newly created socket is closed on exec() if global variable
+ * su_socket_close_on_exec is set to true. Note that a multithreaded program
+ * can fork() and exec() before the close-on-exec flag is set.
+ *
+ * @return A valid socket descriptor or INVALID_SOCKET (-1) upon an error.
+ */
 su_socket_t su_socket(int af, int socktype, int proto)
 {
   su_socket_t s = socket(af, socktype, proto);
-#if SU_HAVE_BSDSOCK
   if (s != INVALID_SOCKET) {
+#if SU_HAVE_BSDSOCK
     if (su_socket_close_on_exec)
       fcntl(s, F_SETFD, FD_CLOEXEC); /* Close on exec */
+#endif
     if (!su_socket_blocking)	/* All sockets are born blocking */
       su_setblocking(s, 0);
   }
-#endif
   return s;
 }
 
-#if SU_HAVE_BSDSOCK
+#if SU_HAVE_BSDSOCK || DOCUMENTATION_ONLY
+/** Initialize socket implementation.
+ *
+ * Before using any sofia-sip-ua functions, the application should call
+ * su_init() in order to initialize run-time environment including sockets. 
+ * This function may prepare plugins if there are any. 
+ *
+ * @par POSIX Implementation
+ * The su_init() initializes debugging logs and ignores the SIGPIPE signal.
+ *
+ * @par Windows Implementation
+ * The function su_init() initializes Winsock2 library on Windows.
+ *
+ * @par Symbian Implementation
+ * The function su_init() prompts user to select an access point (interface
+ * towards Internet) and uses the activated access point for the socket
+ * operations.
+ */
 int su_init(void)
 {
-  su_home_threadsafe(NULL);
-
 #if HAVE_SIGPIPE
   signal(SIGPIPE, SIG_IGN);	/* we want to get EPIPE instead */
 #endif
@@ -83,6 +112,7 @@ int su_init(void)
   return 0;
 }
 
+/** Deinitialize socket implementation. */
 void su_deinit(void)
 {
 }
@@ -133,7 +163,7 @@ void su_deinit(void)
   WSACleanup();
 }
 
-/** Close an socket descriptor. */
+/** Close a socket descriptor. */
 int su_close(su_socket_t s)
 {
   return closesocket(s);
@@ -222,8 +252,9 @@ struct in_addr6 const *su_in6addr_loopback(void)
 }
 #endif
 
-#if SU_HAVE_WINSOCK
+#if SU_HAVE_WINSOCK || DOCUMENTATION_ONLY
 
+/** Call send() with POSIX-compatible signature */
 ssize_t su_send(su_socket_t s, void *buffer, size_t length, int flags)
 {
   if (length > INT_MAX)
@@ -231,6 +262,7 @@ ssize_t su_send(su_socket_t s, void *buffer, size_t length, int flags)
   return (ssize_t)send(s, buffer, (int)length, flags);
 }
 
+/** Call sendto() with POSIX-compatible signature */
 ssize_t su_sendto(su_socket_t s, void *buffer, size_t length, int flags,
 		   su_sockaddr_t const *to, socklen_t tolen)
 {
@@ -240,6 +272,7 @@ ssize_t su_sendto(su_socket_t s, void *buffer, size_t length, int flags,
 			 &to->su_sa, (int) tolen);
 }
 
+/** Call recv() with POSIX-compatible signature */
 ssize_t su_recv(su_socket_t s, void *buffer, size_t length, int flags)
 {
   if (length > INT_MAX)
@@ -248,6 +281,7 @@ ssize_t su_recv(su_socket_t s, void *buffer, size_t length, int flags)
   return (ssize_t)recv(s, buffer, (int)length, flags);
 }
 
+/** Call recvfrom() with POSIX-compatible signature */
 ssize_t su_recvfrom(su_socket_t s, void *buffer, size_t length, int flags,
 		    su_sockaddr_t *from, socklen_t *fromlen)
 {

libsofia-sip-ua/su/su_default_log.c

@@ -53,7 +53,7 @@ static void default_logger(void *stream, char const *fmt, va_list ap)
  * The SOFIA_DEBUG environment variable is used to determine the default
  * debug logging level. The normal level is 3.
  * 
- * @sa <su_debug.h>, su_log_global
+ * @sa <sofia-sip/su_debug.h>, su_log_global
  */
 extern char const SOFIA_DEBUG[];
 

libsofia-sip-ua/su/su_global_log.c

@@ -45,7 +45,7 @@
  * The SU_DEBUG environment variable is used to determine the debug logging
  * level for @b su module. The default level is 3.
  * 
- * @sa <su_debug.h>, su_log_global
+ * @sa <sofia-sip/su_debug.h>, su_log_global
  */
 extern char const SU_DEBUG[];
 

libsofia-sip-ua/su/su_taglist.c

@@ -66,7 +66,7 @@ unsigned longlong strtoull(const char *, char **, int);
  *
  * Object-oriented tag routines for Sofia utility library.
  *
- * The <su_tag.h> defines a interface to object-oriented tag list routines. 
+ * The <sofia-sip/su_tag.h> defines a interface to object-oriented tag list routines. 
  * A tag list is a linear list (array) of tag items, tagi_t structures,
  * terminated by a TAG_END() item. Each tag item has a label, tag, (@c
  * t_tag) and a value (@c t_value). The tag is a pointer (tag_type_t) to a
@@ -112,7 +112,7 @@ unsigned longlong strtoull(const char *, char **, int);
  * - TAG_NEXT() - contains a pointer to the next tag list.
  *
  * The tag type structures are declared as tag_typedef_t. They can be
- * defined by the macros found in <su_tag_class.h>. See nta_tag.c or
+ * defined by the macros found in <sofia-sip/su_tag_class.h>. See nta_tag.c or
  * su_tag_test.c for an example.
  *
  */

libsofia-sip-ua/su/su_time.c

@@ -61,7 +61,7 @@
  * OS-independent timing functions and types for the @b su library.
  *  
  * The @b su library provides three different time formats with different
- * ranges and epochs in the file @b su_time.h:
+ * ranges and epochs in <sofia-sip/su_time.h>:
  *
  *   - #su_time_t, second and microsecond as 32-bit values since 1900,
  *   - #su_duration_t, milliseconds between two times, and

libsofia-sip-ua/su/test_poll.c

@@ -24,7 +24,7 @@
 
 /**@ingroup su_root_ex
  * @file test_poll.c
- * Example code for su_wait.h.
+ * Example code for <sofia-sip/su_wait.h>.
  *
  * This file illustrates how the asynchronous connect can be used with @b su.
  *

libsofia-sip-ua/tport/tport_logging.c

@@ -73,7 +73,7 @@ extern char const TPORT_DUMP[];	/* dummy declaration for Doxygen */
  * The TPORT_DEBUG environment variable is used to determine the debug logging
  * level for @b tport module. The default level is 3.
  * 
- * @sa <su_debug.h>, tport_log, SOFIA_DEBUG
+ * @sa <sofia-sip/su_debug.h>, tport_log, SOFIA_DEBUG
  */
 extern char const TPORT_DEBUG[]; /* dummy declaration for Doxygen */