1 /*  2  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>  3  * Copyright (c) 2007-2012 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_INCLUDED_ 28 #define EVENT2_LISTENER_H_INCLUDED_ 29  30 #include <event2/visibility.h> 31  32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35  36 #include <event2/event.h> 37  38 struct sockaddr; 39 struct evconnlistener; 40  41 /** 42    A callback that we invoke when a listener has a new connection. 43  44    @param listener The evconnlistener 45    @param fd The new file descriptor 46    @param addr The source address of the connection 47    @param socklen The length of addr 48    @param user_arg the pointer passed to evconnlistener_new() 49  */ 50 typedef void (*evconnlistener_cb)(struct evconnlistener *, evutil_socket_t, struct sockaddr *, int socklen, void *); 51  52 /** 53    A callback that we invoke when a listener encounters a non-retriable error. 54  55    @param listener The evconnlistener 56    @param user_arg the pointer passed to evconnlistener_new() 57  */ 58 typedef void (*evconnlistener_errorcb)(struct evconnlistener *, void *); 59  60 /** Flag: Indicates that we should not make incoming sockets nonblocking 61  * before passing them to the callback. */ 62 #define LEV_OPT_LEAVE_SOCKETS_BLOCKING    (1u<<0) 63 /** Flag: Indicates that freeing the listener should close the underlying 64  * socket. */ 65 #define LEV_OPT_CLOSE_ON_FREE        (1u<<1) 66 /** Flag: Indicates that we should set the close-on-exec flag, if possible */ 67 #define LEV_OPT_CLOSE_ON_EXEC        (1u<<2) 68 /** Flag: Indicates that we should disable the timeout (if any) between when 69  * this socket is closed and when we can listen again on the same port. */ 70 #define LEV_OPT_REUSEABLE        (1u<<3) 71 /** Flag: Indicates that the listener should be locked so it‘s safe to use 72  * from multiple threadcs at once. */ 73 #define LEV_OPT_THREADSAFE        (1u<<4) 74 /** Flag: Indicates that the listener should be created in disabled 75  * state. Use evconnlistener_enable() to enable it later. */ 76 #define LEV_OPT_DISABLED        (1u<<5) 77 /** Flag: Indicates that the listener should defer accept() until data is 78  * available, if possible.  Ignored on platforms that do not support this. 79  * 80  * This option can help performance for protocols where the client transmits 81  * immediately after connecting.  Do not use this option if your protocol 82  * _doesn‘t_ start out with the client transmitting data, since in that case 83  * this option will sometimes cause the kernel to never tell you about the 84  * connection. 85  * 86  * This option is only supported by evconnlistener_new_bind(): it can‘t 87  * work with evconnlistener_new_fd(), since the listener needs to be told 88  * to use the option before it is actually bound. 89  */ 90 #define LEV_OPT_DEFERRED_ACCEPT        (1u<<6) 91 /** Flag: Indicates that we ask to allow multiple servers (processes or 92  * threads) to bind to the same port if they each set the option.  93  *  94  * SO_REUSEPORT is what most people would expect SO_REUSEADDR to be, however 95  * SO_REUSEPORT does not imply SO_REUSEADDR. 96  * 97  * This is only available on Linux and kernel 3.9+ 98  */ 99 #define LEV_OPT_REUSEABLE_PORT        (1u<<7)100 101 /**102    Allocate a new evconnlistener object to listen for incoming TCP connections103    on a given file descriptor.104 105    @param base The event base to associate the listener with.106    @param cb A callback to be invoked when a new connection arrives.  If the107       callback is NULL, the listener will be treated as disabled until the108       callback is set.109    @param ptr A user-supplied pointer to give to the callback.110    @param flags Any number of LEV_OPT_* flags111    @param backlog Passed to the listen() call to determine the length of the112       acceptable connection backlog.  Set to -1 for a reasonable default.113       Set to 0 if the socket is already listening.114    @param fd The file descriptor to listen on.  It must be a nonblocking115       file descriptor, and it should already be bound to an appropriate116       port and address.117 */118 EVENT2_EXPORT_SYMBOL119 struct evconnlistener *evconnlistener_new(struct event_base *base,120     evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,121     evutil_socket_t fd);122 /**123    Allocate a new evconnlistener object to listen for incoming TCP connections124    on a given address.125 126    @param base The event base to associate the listener with.127    @param cb A callback to be invoked when a new connection arrives. If the128       callback is NULL, the listener will be treated as disabled until the129       callback is set.130    @param ptr A user-supplied pointer to give to the callback.131    @param flags Any number of LEV_OPT_* flags132    @param backlog Passed to the listen() call to determine the length of the133       acceptable connection backlog.  Set to -1 for a reasonable default.134    @param addr The address to listen for connections on.135    @param socklen The length of the address.136  */137 EVENT2_EXPORT_SYMBOL138 struct evconnlistener *evconnlistener_new_bind(struct event_base *base,139     evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,140     const struct sockaddr *sa, int socklen);141 /**142    Disable and deallocate an evconnlistener.143  */144 EVENT2_EXPORT_SYMBOL145 void evconnlistener_free(struct evconnlistener *lev);146 /**147    Re-enable an evconnlistener that has been disabled.148  */149 EVENT2_EXPORT_SYMBOL150 int evconnlistener_enable(struct evconnlistener *lev);151 /**152    Stop listening for connections on an evconnlistener.153  */154 EVENT2_EXPORT_SYMBOL155 int evconnlistener_disable(struct evconnlistener *lev);156 157 /** Return an evconnlistener‘s associated event_base. */158 EVENT2_EXPORT_SYMBOL159 struct event_base *evconnlistener_get_base(struct evconnlistener *lev);160 161 /** Return the socket that an evconnlistner is listening on. */162 EVENT2_EXPORT_SYMBOL163 evutil_socket_t evconnlistener_get_fd(struct evconnlistener *lev);164 165 /** Change the callback on the listener to cb and its user_data to arg.166  */167 EVENT2_EXPORT_SYMBOL168 void evconnlistener_set_cb(struct evconnlistener *lev,169     evconnlistener_cb cb, void *arg);170 171 /** Set an evconnlistener‘s error callback. */172 EVENT2_EXPORT_SYMBOL173 void evconnlistener_set_error_cb(struct evconnlistener *lev,174     evconnlistener_errorcb errorcb);175 176 #ifdef __cplusplus177 }178 #endif179 180 #endif