Commit 1b1fb1ca authored by Pekka Pessi's avatar Pekka Pessi

su: updated documentation

darcs-hash:20070627094304-65a35-adea6070f058da87a281c983f8b7598620ccaad4.gz
parent 1610ff2e
......@@ -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.
......
......@@ -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)
{
......
This diff is collapsed.
......@@ -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[];
......
......@@ -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[];
......
......@@ -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.
*
*/
......
......@@ -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
......
......@@ -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.
*
......
......@@ -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 */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment