su_wait.h

Sofia SIP is an open-source SIP User-Agent library, compliant with the IETF RFC3261 specification.

/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <[e-mail]>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

#ifndef SU_WAIT_H
/** Defined when <sofia-sip/su_wait.h> has been included. */
#define SU_WAIT_H

/**@ingroup su_wait
 * @file sofia-sip/su_wait.h Syncronization and threading interface.
 *
 * @author Pekka Pessi <[e-mail]>
 * @author Martti Mela <[e-mail]>
 * 
 * @date Created: Tue Sep 14 15:51:04 1999 ppessi
 */

/* ---------------------------------------------------------------------- */
/* Includes */

#ifndef SU_H
#include "sofia-sip/su.h"
#endif

#ifndef SU_TIME_H
#include "sofia-sip/su_time.h"
#endif

#if SU_HAVE_POLL
#include <sys/poll.h>
#endif

SOFIA_BEGIN_DECLS

/* ---------------------------------------------------------------------- */
/* Constants */

#if SU_HAVE_KQUEUE
/** Compare wait object. @HI */
#define SU_WAIT_CMP(x, y) \
 (((x).ident - (y).ident) ? ((x).ident - (y).ident) : ((x).flags - (y).flags))

/** Incoming data is available on socket. @HI */
#define SU_WAIT_IN      (EVFILT_READ)
/** Data can be sent on socket. @HI */
#define SU_WAIT_OUT     (EVFILT_WRITE)
/** Socket is connected. @HI */
#define SU_WAIT_CONNECT (EVFILT_WRITE)
/** An error occurred on socket. @HI */
#define SU_WAIT_ERR     (EV_ERROR)
/** The socket connection was closed. @HI */
#define SU_WAIT_HUP     (EV_EOF)
/** A listening socket accepted a new connection. @HI */
#define SU_WAIT_ACCEPT  (EVFILT_READ)

/** No timeout for su_wait(). */
#define SU_WAIT_FOREVER (-1)
/** The return value of su_wait() if timeout occurred. */
#define SU_WAIT_TIMEOUT (-2)

/** Initializer for a wait object. @HI */
#define SU_WAIT_INIT    { INVALID_SOCKET, 0, 0, 0, 0, NULL }

/** Maximum number of sources supported by su_wait() */
#define SU_WAIT_MAX    (0x7fffffff)

#elif SU_HAVE_POLL || DOCUMENTATION_ONLY
/** Compare wait object. @HI */
#define SU_WAIT_CMP(x, y) \
 (((x).fd - (y).fd) ? ((x).fd - (y).fd) : ((x).events - (y).events))

/** Incoming data is available on socket. @HI */
#define SU_WAIT_IN      (POLLIN)
/** Data can be sent on socket. @HI */
#define SU_WAIT_OUT     (POLLOUT)
/** Socket is connected. @HI */
#define SU_WAIT_CONNECT (POLLOUT)
/** An error occurred on socket. @HI */
#define SU_WAIT_ERR     (POLLERR)
/** The socket connection was closed. @HI */
#define SU_WAIT_HUP     (POLLHUP)
/** A listening socket accepted a new connection. @HI */
#define SU_WAIT_ACCEPT  (POLLIN)

/** No timeout for su_wait(). */
#define SU_WAIT_FOREVER (-1)
/** The return value of su_wait() if timeout occurred. */
#define SU_WAIT_TIMEOUT (-2)

/** Initializer for a wait object. @HI */
#define SU_WAIT_INIT    { INVALID_SOCKET, 0, 0 }

/** Maximum number of sources supported by su_wait() */
#define SU_WAIT_MAX    (0x7fffffff)

#elif SU_HAVE_WINSOCK

#define SU_WAIT_CMP(x, y) ((intptr_t)(x) - (intptr_t)(y))

#define SU_WAIT_IN      (FD_READ)
#define SU_WAIT_OUT     (FD_WRITE)
#define SU_WAIT_CONNECT (FD_CONNECT)
#define SU_WAIT_ERR     (0)	/* let's get it on */
#define SU_WAIT_HUP     (FD_CLOSE)
#define SU_WAIT_ACCEPT  (FD_ACCEPT)

#define SU_WAIT_FOREVER (WSA_INFINITE)
#define SU_WAIT_TIMEOUT (WSA_WAIT_TIMEOUT)

#define SU_WAIT_INIT    NULL

#define SU_WAIT_MAX    (64)

#else
/* If nothing works, try these */

#define	POLLIN		0x001
#define	POLLPRI		0x002
#define	POLLOUT		0x004

#ifdef __USE_XOPEN
#define	POLLRDNORM	0x040
#define	POLLRDBAND	0x080
#define	POLLWRNORM	0x100
#define	POLLWRBAND	0x200
#endif

/* These for pollfd.revents */
#define POLLERR         0x008
#define POLLHUP         0x010
#define POLLNVAL        0x020

#define SU_WAIT_CMP(x, y) \
 (((x).fd - (y).fd) ? ((x).fd - (y).fd) : ((x).events - (y).events))

#define SU_WAIT_IN      POLLIN
#define SU_WAIT_OUT     POLLOUT
#define SU_WAIT_CONNECT POLLOUT
#define SU_WAIT_ERR     POLLERR
#define SU_WAIT_HUP     POLLHUP
#define SU_WAIT_ACCEPT  POLLIN
#define SU_WAIT_FOREVER (-1)
#define SU_WAIT_TIMEOUT (-2)

#define SU_WAIT_INIT    { INVALID_SOCKET, 0, 0 }

/** Maximum number of sources supported by su_wait() */
#define SU_WAIT_MAX    (0x7fffffff)

#endif

/* ---------------------------------------------------------------------- */
/* Types */

/** Wait object. */
#if SU_HAVE_KQUEUE
typedef struct kevent su_wait_t;
#elif SU_HAVE_POLL
typedef struct pollfd su_wait_t;
#elif SU_HAVE_WINSOCK
typedef HANDLE su_wait_t;
#else
/* typedef struct os_specific su_wait_t; */
typedef struct pollfd su_wait_t;
struct pollfd {
  su_socket_t fd;   /* file descriptor */
  short events;     /* requested events */
  short revents;    /* returned events */
};


/* Type used for the number of file descriptors.  */
typedef unsigned long int nfds_t;

/* Poll the file descriptors described by the NFDS structures starting at
   FDS.  If TIMEOUT is nonzero and not -1, allow TIMEOUT milliseconds for
   an event to occur; if TIMEOUT is -1, block until an event occurs.
   Returns the number of file descriptors with events, zero if timed out,
   or -1 for errors.  */
int poll (struct pollfd *__fds, nfds_t __nfds, int __timeout);

#endif

/* Used by AD */
typedef int su_success_t;

/* ---------------------------------------------------------------------- */

/** <a href="#su_root_t">Root object</a> type. */
typedef struct su_root_s su_root_t;

#ifndef SU_ROOT_MAGIC_T
/**Default type of application context for <a href="#su_root_t">su_root_t</a>.
 *
 * Application may define the typedef ::su_root_magic_t to appropriate type
 * by defining macro SU_ROOT_MAGIC_T before including <sofia-sip/su_wait.h>, for
 * example,
 * @code
 * #define SU_ROOT_MAGIC_T struct context
f * #include <sofia-sip/su_wait.h>
 * @endcode
 */
#define SU_ROOT_MAGIC_T void
#endif

/** <a href="#su_root_t">Root context</a> pointer type.
 *
 * Application may define the typedef ::su_root_magic_t to appropriate type
 * by defining macro SU_ROOT_MAGIC_T () before including <sofia-sip/su_wait.h>, for
 * example,
 * @code
 * #define SU_ROOT_MAGIC_T struct context
 * #include <sofia-sip/su_wait.h>
 * @endcode
 */
typedef SU_ROOT_MAGIC_T su_root_magic_t;

#ifndef SU_WAKEUP_ARG_T
/**Default type of @link ::su_wakeup_f wakeup function @endlink 
 * @link ::su_wakeup_arg_t argument type @endlink.  
 *
 * The application can define the typedef ::su_wakeup_arg_t by defining
 * the SU_WAKEUP_ARG_T () before including <sofia-sip/su_wait.h>, for example,
 * @code
 * #define SU_WAKEUP_ARG_T struct transport
 * #include <sofia-sip/su_wait.h>
 * @endcode
 */
#define SU_WAKEUP_ARG_T void
#endif

/** @link ::su_wakeup_f Wakeup callback @endlink argument type. 
 *
 * The application can define the typedef ::su_wakeup_arg_t by defining
 * the SU_WAKEUP_ARG_T () before including <sofia-sip/su_wait.h>, for example,
 * @code
 * #define SU_WAKEUP_ARG_T struct transport
 * #include <sofia-sip/su_wait.h>
 * @endcode
 */
typedef SU_WAKEUP_ARG_T su_wakeup_arg_t;

/** Wakeup callback function pointer type. 
 *
 * Whenever a registered wait object receives an event, the @link
 * ::su_wakeup_f callback function @endlink is invoked.
 */
typedef int (*su_wakeup_f)(su_root_magic_t *,
			   su_wait_t *,
			   su_wakeup_arg_t *arg);

enum { 
  su_pri_normal,		/**< Normal priority */
  su_pri_first,			/**< Elevated priority */
  su_pri_realtime		/**< Real-time priority */
};

struct _GSource;

/** Hint for number of registered fds in su_root */
SOFIAPUBVAR int su_root_size_hint;

/* ---------------------------------------------------------------------- */
/* Pre-poll callback */

#ifndef SU_PREPOLL_MAGIC_T
/**Default type of application context for prepoll function.
 *
 * Application may define the typedef ::su_prepoll_magic_t to appropriate type
 * by defining macro #SU_PREPOLL_MAGIC_T before including <sofia-sip/su_wait.h>, for
 * example,
 * @code
 * #define SU_PREPOLL_MAGIC_T struct context
 * #include <sofia-sip/su_wait.h>
 * @endcode
 */
#define SU_PREPOLL_MAGIC_T void
#endif

/** <a href="#su_root_t">Root context</a> pointer type.
 *
 * Application may define the typedef ::su_prepoll_magic_t to appropriate type
 * by defining macro #SU_PREPOLL_MAGIC_T before including <sofia-sip/su_wait.h>, for