libevent/include/event2/listener.h

   1 /*
   2  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
   3  * Copyright (c) 2007-2010 Niels Provos and Nick Mathewson
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  * 3. The name of the author may not be used to endorse or promote products
  14  *    derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27 #ifndef _EVENT2_LISTENER_H_
  28 #define _EVENT2_LISTENER_H_
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 #include <event2/event.h>
  35
  36 struct sockaddr;
  37 struct evconnlistener;
  38
  39 /**
  40    A callback that we invoke when a listener has a new connection.
  41
  42    @param listener The evconnlistener
  43    @param fd The new file descriptor
  44    @param addr The source address of the connection
  45    @param socklen The length of addr
  46    @param user_arg the pointer passed to evconnlistener_new()
  47  */
  48 typedef void (*evconnlistener_cb)(struct evconnlistener *, evutil_socket_t, struct sockaddr *, int socklen, void *);
  49
  50 /**
  51    A callback that we invoke when a listener encounters a non-retriable error.
  52
  53    @param listener The evconnlistener
  54    @param user_arg the pointer passed to evconnlistener_new()
  55  */
  56 typedef void (*evconnlistener_errorcb)(struct evconnlistener *, void *);
  57
  58 /** Flag: Indicates that we should not make incoming sockets nonblocking
  59  * before passing them to the callback. */
  60 #define LEV_OPT_LEAVE_SOCKETS_BLOCKING  (1u<<0)
  61 /** Flag: Indicates that freeing the listener should close the underlying
  62  * socket. */
  63 #define LEV_OPT_CLOSE_ON_FREE           (1u<<1)
  64 /** Flag: Indicates that we should set the close-on-exec flag, if possible */
  65 #define LEV_OPT_CLOSE_ON_EXEC           (1u<<2)
  66 /** Flag: Indicates that we should disable the timeout (if any) between when
  67  * this socket is closed and when we can listen again on the same port. */
  68 #define LEV_OPT_REUSEABLE               (1u<<3)
  69 /** Flag: Indicates that the listener should be locked so it's safe to use
  70  * from multiple threadcs at once. */
  71 #define LEV_OPT_THREADSAFE              (1u<<4)
  72
  73 /**
  74    Allocate a new evconnlistener object to listen for incoming TCP connections
  75    on a given file descriptor.
  76
  77    @param base The event base to associate the listener with.
  78    @param cb A callback to be invoked when a new connection arrives.  If the
  79       callback is NULL, the listener will be treated as disabled until the
  80       callback is set.
  81    @param ptr A user-supplied pointer to give to the callback.
  82    @param flags Any number of LEV_OPT_* flags
  83    @param backlog Passed to the listen() call to determine the length of the
  84       acceptable connection backlog.  Set to -1 for a reasonable default.
  85       Set to 0 if the socket is already listening.
  86    @param fd The file descriptor to listen on.  It must be a nonblocking
  87       file descriptor, and it should already be bound to an appropriate
  88       port and address.
  89 */
  90 struct evconnlistener *evconnlistener_new(struct event_base *base,
  91     evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
  92     evutil_socket_t fd);
  93 /**
  94    Allocate a new evconnlistener object to listen for incoming TCP connections
  95    on a given address.
  96
  97    @param base The event base to associate the listener with.
  98    @param cb A callback to be invoked when a new connection arrives. If the
  99       callback is NULL, the listener will be treated as disabled until the
 100       callback is set.
 101    @param ptr A user-supplied pointer to give to the callback.
 102    @param flags Any number of LEV_OPT_* flags
 103    @param backlog Passed to the listen() call to determine the length of the
 104       acceptable connection backlog.  Set to -1 for a reasonable default.
 105    @param addr The address to listen for connections on.
 106    @param socklen The length of the address.
 107  */
 108 struct evconnlistener *evconnlistener_new_bind(struct event_base *base,
 109     evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
 110     const struct sockaddr *sa, int socklen);
 111 /**
 112    Disable and deallocate an evconnlistener.
 113  */
 114 void evconnlistener_free(struct evconnlistener *lev);
 115 /**
 116    Re-enable an evconnlistener that has been disabled.
 117  */
 118 int evconnlistener_enable(struct evconnlistener *lev);
 119 /**
 120    Stop listening for connections on an evconnlistener.
 121  */
 122 int evconnlistener_disable(struct evconnlistener *lev);
 123
 124 /** Return an evconnlistener's associated event_base. */
 125 struct event_base *evconnlistener_get_base(struct evconnlistener *lev);
 126
 127 /** Return the socket that an evconnlistner is listening on. */
 128 evutil_socket_t evconnlistener_get_fd(struct evconnlistener *lev);
 129
 130 /** Change the callback on the listener to cb and its user_data to arg.
 131  */
 132 void evconnlistener_set_cb(struct evconnlistener *lev,
 133     evconnlistener_cb cb, void *arg);
 134
 135 /** Set an evconnlistener's error callback. */
 136 void evconnlistener_set_error_cb(struct evconnlistener *lev,
 137     evconnlistener_errorcb errorcb);
 138
 139 #ifdef __cplusplus
 140 }
 141 #endif
 142
 143 #endif