12b15cb3dSCy Schubert /* 22b15cb3dSCy Schubert * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu> 32b15cb3dSCy Schubert * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 42b15cb3dSCy Schubert * 52b15cb3dSCy Schubert * Redistribution and use in source and binary forms, with or without 62b15cb3dSCy Schubert * modification, are permitted provided that the following conditions 72b15cb3dSCy Schubert * are met: 82b15cb3dSCy Schubert * 1. Redistributions of source code must retain the above copyright 92b15cb3dSCy Schubert * notice, this list of conditions and the following disclaimer. 102b15cb3dSCy Schubert * 2. Redistributions in binary form must reproduce the above copyright 112b15cb3dSCy Schubert * notice, this list of conditions and the following disclaimer in the 122b15cb3dSCy Schubert * documentation and/or other materials provided with the distribution. 132b15cb3dSCy Schubert * 3. The name of the author may not be used to endorse or promote products 142b15cb3dSCy Schubert * derived from this software without specific prior written permission. 152b15cb3dSCy Schubert * 162b15cb3dSCy Schubert * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 172b15cb3dSCy Schubert * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 182b15cb3dSCy Schubert * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 192b15cb3dSCy Schubert * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 202b15cb3dSCy Schubert * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 212b15cb3dSCy Schubert * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 222b15cb3dSCy Schubert * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 232b15cb3dSCy Schubert * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 242b15cb3dSCy Schubert * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 252b15cb3dSCy Schubert * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 262b15cb3dSCy Schubert */ 272b15cb3dSCy Schubert #ifndef EVENT2_BUFFEREVENT_H_INCLUDED_ 282b15cb3dSCy Schubert #define EVENT2_BUFFEREVENT_H_INCLUDED_ 292b15cb3dSCy Schubert 302b15cb3dSCy Schubert /** 312b15cb3dSCy Schubert @file event2/bufferevent.h 322b15cb3dSCy Schubert 332b15cb3dSCy Schubert Functions for buffering data for network sending or receiving. Bufferevents 342b15cb3dSCy Schubert are higher level than evbuffers: each has an underlying evbuffer for reading 352b15cb3dSCy Schubert and one for writing, and callbacks that are invoked under certain 362b15cb3dSCy Schubert circumstances. 372b15cb3dSCy Schubert 382b15cb3dSCy Schubert A bufferevent provides input and output buffers that get filled and 392b15cb3dSCy Schubert drained automatically. The user of a bufferevent no longer deals 402b15cb3dSCy Schubert directly with the I/O, but instead is reading from input and writing 412b15cb3dSCy Schubert to output buffers. 422b15cb3dSCy Schubert 432b15cb3dSCy Schubert Once initialized, the bufferevent structure can be used repeatedly 442b15cb3dSCy Schubert with bufferevent_enable() and bufferevent_disable(). 452b15cb3dSCy Schubert 462b15cb3dSCy Schubert When reading is enabled, the bufferevent will try to read from the 472b15cb3dSCy Schubert file descriptor onto its input buffer, and call the read callback. 482b15cb3dSCy Schubert When writing is enabled, the bufferevent will try to write data onto its 492b15cb3dSCy Schubert file descriptor when the output buffer has enough data, and call the write 502b15cb3dSCy Schubert callback when the output buffer is sufficiently drained. 512b15cb3dSCy Schubert 522b15cb3dSCy Schubert Bufferevents come in several flavors, including: 532b15cb3dSCy Schubert 542b15cb3dSCy Schubert <dl> 552b15cb3dSCy Schubert <dt>Socket-based bufferevents</dt> 562b15cb3dSCy Schubert <dd>A bufferevent that reads and writes data onto a network 572b15cb3dSCy Schubert socket. Created with bufferevent_socket_new().</dd> 582b15cb3dSCy Schubert 592b15cb3dSCy Schubert <dt>Paired bufferevents</dt> 602b15cb3dSCy Schubert <dd>A pair of bufferevents that send and receive data to one 612b15cb3dSCy Schubert another without touching the network. Created with 622b15cb3dSCy Schubert bufferevent_pair_new().</dd> 632b15cb3dSCy Schubert 642b15cb3dSCy Schubert <dt>Filtering bufferevents</dt> 652b15cb3dSCy Schubert <dd>A bufferevent that transforms data, and sends or receives it 662b15cb3dSCy Schubert over another underlying bufferevent. Created with 672b15cb3dSCy Schubert bufferevent_filter_new().</dd> 682b15cb3dSCy Schubert 692b15cb3dSCy Schubert <dt>SSL-backed bufferevents</dt> 702b15cb3dSCy Schubert <dd>A bufferevent that uses the openssl library to send and 712b15cb3dSCy Schubert receive data over an encrypted connection. Created with 722b15cb3dSCy Schubert bufferevent_openssl_socket_new() or 732b15cb3dSCy Schubert bufferevent_openssl_filter_new().</dd> 742b15cb3dSCy Schubert </dl> 752b15cb3dSCy Schubert */ 762b15cb3dSCy Schubert 772b15cb3dSCy Schubert #include <event2/visibility.h> 782b15cb3dSCy Schubert 792b15cb3dSCy Schubert #ifdef __cplusplus 802b15cb3dSCy Schubert extern "C" { 812b15cb3dSCy Schubert #endif 822b15cb3dSCy Schubert 832b15cb3dSCy Schubert #include <event2/event-config.h> 842b15cb3dSCy Schubert #ifdef EVENT__HAVE_SYS_TYPES_H 852b15cb3dSCy Schubert #include <sys/types.h> 862b15cb3dSCy Schubert #endif 872b15cb3dSCy Schubert #ifdef EVENT__HAVE_SYS_TIME_H 882b15cb3dSCy Schubert #include <sys/time.h> 892b15cb3dSCy Schubert #endif 902b15cb3dSCy Schubert 912b15cb3dSCy Schubert /* For int types. */ 922b15cb3dSCy Schubert #include <event2/util.h> 932b15cb3dSCy Schubert 942b15cb3dSCy Schubert /** @name Bufferevent event codes 952b15cb3dSCy Schubert 962b15cb3dSCy Schubert These flags are passed as arguments to a bufferevent's event callback. 972b15cb3dSCy Schubert 982b15cb3dSCy Schubert @{ 992b15cb3dSCy Schubert */ 1002b15cb3dSCy Schubert #define BEV_EVENT_READING 0x01 /**< error encountered while reading */ 1012b15cb3dSCy Schubert #define BEV_EVENT_WRITING 0x02 /**< error encountered while writing */ 1022b15cb3dSCy Schubert #define BEV_EVENT_EOF 0x10 /**< eof file reached */ 1032b15cb3dSCy Schubert #define BEV_EVENT_ERROR 0x20 /**< unrecoverable error encountered */ 1042b15cb3dSCy Schubert #define BEV_EVENT_TIMEOUT 0x40 /**< user-specified timeout reached */ 1052b15cb3dSCy Schubert #define BEV_EVENT_CONNECTED 0x80 /**< connect operation finished. */ 1062b15cb3dSCy Schubert /**@}*/ 1072b15cb3dSCy Schubert 1082b15cb3dSCy Schubert /** 1092b15cb3dSCy Schubert An opaque type for handling buffered IO 1102b15cb3dSCy Schubert 1112b15cb3dSCy Schubert @see event2/bufferevent.h 1122b15cb3dSCy Schubert */ 1132b15cb3dSCy Schubert struct bufferevent 1142b15cb3dSCy Schubert #ifdef EVENT_IN_DOXYGEN_ 1152b15cb3dSCy Schubert {} 1162b15cb3dSCy Schubert #endif 1172b15cb3dSCy Schubert ; 1182b15cb3dSCy Schubert struct event_base; 1192b15cb3dSCy Schubert struct evbuffer; 1202b15cb3dSCy Schubert struct sockaddr; 1212b15cb3dSCy Schubert 1222b15cb3dSCy Schubert /** 1232b15cb3dSCy Schubert A read or write callback for a bufferevent. 1242b15cb3dSCy Schubert 1252b15cb3dSCy Schubert The read callback is triggered when new data arrives in the input 1262b15cb3dSCy Schubert buffer and the amount of readable data exceed the low watermark 1272b15cb3dSCy Schubert which is 0 by default. 1282b15cb3dSCy Schubert 1292b15cb3dSCy Schubert The write callback is triggered if the write buffer has been 1302b15cb3dSCy Schubert exhausted or fell below its low watermark. 1312b15cb3dSCy Schubert 1322b15cb3dSCy Schubert @param bev the bufferevent that triggered the callback 1332b15cb3dSCy Schubert @param ctx the user-specified context for this bufferevent 1342b15cb3dSCy Schubert */ 1352b15cb3dSCy Schubert typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx); 1362b15cb3dSCy Schubert 1372b15cb3dSCy Schubert /** 1382b15cb3dSCy Schubert An event/error callback for a bufferevent. 1392b15cb3dSCy Schubert 1402b15cb3dSCy Schubert The event callback is triggered if either an EOF condition or another 1412b15cb3dSCy Schubert unrecoverable error was encountered. 1422b15cb3dSCy Schubert 1432b15cb3dSCy Schubert For bufferevents with deferred callbacks, this is a bitwise OR of all errors 1442b15cb3dSCy Schubert that have happened on the bufferevent since the last callback invocation. 1452b15cb3dSCy Schubert 1462b15cb3dSCy Schubert @param bev the bufferevent for which the error condition was reached 1472b15cb3dSCy Schubert @param what a conjunction of flags: BEV_EVENT_READING or BEV_EVENT_WRITING 1482b15cb3dSCy Schubert to indicate if the error was encountered on the read or write path, 1492b15cb3dSCy Schubert and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR, 1502b15cb3dSCy Schubert BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED. 1512b15cb3dSCy Schubert 1522b15cb3dSCy Schubert @param ctx the user-specified context for this bufferevent 1532b15cb3dSCy Schubert */ 1542b15cb3dSCy Schubert typedef void (*bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx); 1552b15cb3dSCy Schubert 1562b15cb3dSCy Schubert /** Options that can be specified when creating a bufferevent */ 1572b15cb3dSCy Schubert enum bufferevent_options { 1582b15cb3dSCy Schubert /** If set, we close the underlying file 1592b15cb3dSCy Schubert * descriptor/bufferevent/whatever when this bufferevent is freed. */ 1602b15cb3dSCy Schubert BEV_OPT_CLOSE_ON_FREE = (1<<0), 1612b15cb3dSCy Schubert 1622b15cb3dSCy Schubert /** If set, and threading is enabled, operations on this bufferevent 1632b15cb3dSCy Schubert * are protected by a lock */ 1642b15cb3dSCy Schubert BEV_OPT_THREADSAFE = (1<<1), 1652b15cb3dSCy Schubert 1662b15cb3dSCy Schubert /** If set, callbacks are run deferred in the event loop. */ 1672b15cb3dSCy Schubert BEV_OPT_DEFER_CALLBACKS = (1<<2), 1682b15cb3dSCy Schubert 1692b15cb3dSCy Schubert /** If set, callbacks are executed without locks being held on the 1702b15cb3dSCy Schubert * bufferevent. This option currently requires that 1712b15cb3dSCy Schubert * BEV_OPT_DEFER_CALLBACKS also be set; a future version of Libevent 1722b15cb3dSCy Schubert * might remove the requirement.*/ 1732b15cb3dSCy Schubert BEV_OPT_UNLOCK_CALLBACKS = (1<<3) 1742b15cb3dSCy Schubert }; 1752b15cb3dSCy Schubert 1762b15cb3dSCy Schubert /** 1772b15cb3dSCy Schubert Create a new socket bufferevent over an existing socket. 1782b15cb3dSCy Schubert 1792b15cb3dSCy Schubert @param base the event base to associate with the new bufferevent. 1802b15cb3dSCy Schubert @param fd the file descriptor from which data is read and written to. 1812b15cb3dSCy Schubert This file descriptor is not allowed to be a pipe(2). 1822b15cb3dSCy Schubert It is safe to set the fd to -1, so long as you later 1832b15cb3dSCy Schubert set it with bufferevent_setfd or bufferevent_socket_connect(). 1842b15cb3dSCy Schubert @param options Zero or more BEV_OPT_* flags 1852b15cb3dSCy Schubert @return a pointer to a newly allocated bufferevent struct, or NULL if an 1862b15cb3dSCy Schubert error occurred 1872b15cb3dSCy Schubert @see bufferevent_free() 1882b15cb3dSCy Schubert */ 1892b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 1902b15cb3dSCy Schubert struct bufferevent *bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options); 1912b15cb3dSCy Schubert 1922b15cb3dSCy Schubert /** 1932b15cb3dSCy Schubert Launch a connect() attempt with a socket-based bufferevent. 1942b15cb3dSCy Schubert 1952b15cb3dSCy Schubert When the connect succeeds, the eventcb will be invoked with 1962b15cb3dSCy Schubert BEV_EVENT_CONNECTED set. 1972b15cb3dSCy Schubert 1982b15cb3dSCy Schubert If the bufferevent does not already have a socket set, we allocate a new 1992b15cb3dSCy Schubert socket here and make it nonblocking before we begin. 2002b15cb3dSCy Schubert 2012b15cb3dSCy Schubert If no address is provided, we assume that the socket is already connecting, 2022b15cb3dSCy Schubert and configure the bufferevent so that a BEV_EVENT_CONNECTED event will be 2032b15cb3dSCy Schubert yielded when it is done connecting. 2042b15cb3dSCy Schubert 2052b15cb3dSCy Schubert @param bufev an existing bufferevent allocated with 2062b15cb3dSCy Schubert bufferevent_socket_new(). 2072b15cb3dSCy Schubert @param addr the address we should connect to 2082b15cb3dSCy Schubert @param socklen The length of the address 2092b15cb3dSCy Schubert @return 0 on success, -1 on failure. 2102b15cb3dSCy Schubert */ 2112b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 212*a466cc55SCy Schubert int bufferevent_socket_connect(struct bufferevent *, const struct sockaddr *, int); 2132b15cb3dSCy Schubert 2142b15cb3dSCy Schubert struct evdns_base; 2152b15cb3dSCy Schubert /** 2162b15cb3dSCy Schubert Resolve the hostname 'hostname' and connect to it as with 2172b15cb3dSCy Schubert bufferevent_socket_connect(). 2182b15cb3dSCy Schubert 2192b15cb3dSCy Schubert @param bufev An existing bufferevent allocated with bufferevent_socket_new() 2202b15cb3dSCy Schubert @param evdns_base Optionally, an evdns_base to use for resolving hostnames 2212b15cb3dSCy Schubert asynchronously. May be set to NULL for a blocking resolve. 2222b15cb3dSCy Schubert @param family A preferred address family to resolve addresses to, or 2232b15cb3dSCy Schubert AF_UNSPEC for no preference. Only AF_INET, AF_INET6, and AF_UNSPEC are 2242b15cb3dSCy Schubert supported. 2252b15cb3dSCy Schubert @param hostname The hostname to resolve; see below for notes on recognized 2262b15cb3dSCy Schubert formats 2272b15cb3dSCy Schubert @param port The port to connect to on the resolved address. 2282b15cb3dSCy Schubert @return 0 if successful, -1 on failure. 2292b15cb3dSCy Schubert 2302b15cb3dSCy Schubert Recognized hostname formats are: 2312b15cb3dSCy Schubert 2322b15cb3dSCy Schubert www.example.com (hostname) 2332b15cb3dSCy Schubert 1.2.3.4 (ipv4address) 2342b15cb3dSCy Schubert ::1 (ipv6address) 2352b15cb3dSCy Schubert [::1] ([ipv6address]) 2362b15cb3dSCy Schubert 2372b15cb3dSCy Schubert Performance note: If you do not provide an evdns_base, this function 2382b15cb3dSCy Schubert may block while it waits for a DNS response. This is probably not 2392b15cb3dSCy Schubert what you want. 2402b15cb3dSCy Schubert */ 2412b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 2422b15cb3dSCy Schubert int bufferevent_socket_connect_hostname(struct bufferevent *, 2432b15cb3dSCy Schubert struct evdns_base *, int, const char *, int); 2442b15cb3dSCy Schubert 2452b15cb3dSCy Schubert /** 2462b15cb3dSCy Schubert Return the error code for the last failed DNS lookup attempt made by 2472b15cb3dSCy Schubert bufferevent_socket_connect_hostname(). 2482b15cb3dSCy Schubert 2492b15cb3dSCy Schubert @param bev The bufferevent object. 2502b15cb3dSCy Schubert @return DNS error code. 2512b15cb3dSCy Schubert @see evutil_gai_strerror() 2522b15cb3dSCy Schubert */ 2532b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 2542b15cb3dSCy Schubert int bufferevent_socket_get_dns_error(struct bufferevent *bev); 2552b15cb3dSCy Schubert 2562b15cb3dSCy Schubert /** 2572b15cb3dSCy Schubert Assign a bufferevent to a specific event_base. 2582b15cb3dSCy Schubert 2592b15cb3dSCy Schubert NOTE that only socket bufferevents support this function. 2602b15cb3dSCy Schubert 2612b15cb3dSCy Schubert @param base an event_base returned by event_init() 2622b15cb3dSCy Schubert @param bufev a bufferevent struct returned by bufferevent_new() 2632b15cb3dSCy Schubert or bufferevent_socket_new() 2642b15cb3dSCy Schubert @return 0 if successful, or -1 if an error occurred 2652b15cb3dSCy Schubert @see bufferevent_new() 2662b15cb3dSCy Schubert */ 2672b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 2682b15cb3dSCy Schubert int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev); 2692b15cb3dSCy Schubert 2702b15cb3dSCy Schubert /** 2712b15cb3dSCy Schubert Return the event_base used by a bufferevent 2722b15cb3dSCy Schubert */ 2732b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 2742b15cb3dSCy Schubert struct event_base *bufferevent_get_base(struct bufferevent *bev); 2752b15cb3dSCy Schubert 2762b15cb3dSCy Schubert /** 2772b15cb3dSCy Schubert Assign a priority to a bufferevent. 2782b15cb3dSCy Schubert 2792b15cb3dSCy Schubert Only supported for socket bufferevents. 2802b15cb3dSCy Schubert 2812b15cb3dSCy Schubert @param bufev a bufferevent struct 2822b15cb3dSCy Schubert @param pri the priority to be assigned 2832b15cb3dSCy Schubert @return 0 if successful, or -1 if an error occurred 2842b15cb3dSCy Schubert */ 2852b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 2862b15cb3dSCy Schubert int bufferevent_priority_set(struct bufferevent *bufev, int pri); 2872b15cb3dSCy Schubert 2882b15cb3dSCy Schubert /** 2892b15cb3dSCy Schubert Return the priority of a bufferevent. 2902b15cb3dSCy Schubert 2912b15cb3dSCy Schubert Only supported for socket bufferevents 2922b15cb3dSCy Schubert */ 2932b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 2942b15cb3dSCy Schubert int bufferevent_get_priority(const struct bufferevent *bufev); 2952b15cb3dSCy Schubert 2962b15cb3dSCy Schubert /** 2972b15cb3dSCy Schubert Deallocate the storage associated with a bufferevent structure. 2982b15cb3dSCy Schubert 2992b15cb3dSCy Schubert If there is pending data to write on the bufferevent, it probably won't be 3002b15cb3dSCy Schubert flushed before the bufferevent is freed. 3012b15cb3dSCy Schubert 3022b15cb3dSCy Schubert @param bufev the bufferevent structure to be freed. 3032b15cb3dSCy Schubert */ 3042b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 3052b15cb3dSCy Schubert void bufferevent_free(struct bufferevent *bufev); 3062b15cb3dSCy Schubert 3072b15cb3dSCy Schubert 3082b15cb3dSCy Schubert /** 3092b15cb3dSCy Schubert Changes the callbacks for a bufferevent. 3102b15cb3dSCy Schubert 3112b15cb3dSCy Schubert @param bufev the bufferevent object for which to change callbacks 3122b15cb3dSCy Schubert @param readcb callback to invoke when there is data to be read, or NULL if 3132b15cb3dSCy Schubert no callback is desired 3142b15cb3dSCy Schubert @param writecb callback to invoke when the file descriptor is ready for 3152b15cb3dSCy Schubert writing, or NULL if no callback is desired 3162b15cb3dSCy Schubert @param eventcb callback to invoke when there is an event on the file 3172b15cb3dSCy Schubert descriptor 3182b15cb3dSCy Schubert @param cbarg an argument that will be supplied to each of the callbacks 3192b15cb3dSCy Schubert (readcb, writecb, and errorcb) 3202b15cb3dSCy Schubert @see bufferevent_new() 3212b15cb3dSCy Schubert */ 3222b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 3232b15cb3dSCy Schubert void bufferevent_setcb(struct bufferevent *bufev, 3242b15cb3dSCy Schubert bufferevent_data_cb readcb, bufferevent_data_cb writecb, 3252b15cb3dSCy Schubert bufferevent_event_cb eventcb, void *cbarg); 3262b15cb3dSCy Schubert 3272b15cb3dSCy Schubert /** 3282b15cb3dSCy Schubert Retrieves the callbacks for a bufferevent. 3292b15cb3dSCy Schubert 3302b15cb3dSCy Schubert @param bufev the bufferevent to examine. 3312b15cb3dSCy Schubert @param readcb_ptr if readcb_ptr is nonnull, *readcb_ptr is set to the current 3322b15cb3dSCy Schubert read callback for the bufferevent. 3332b15cb3dSCy Schubert @param writecb_ptr if writecb_ptr is nonnull, *writecb_ptr is set to the 3342b15cb3dSCy Schubert current write callback for the bufferevent. 3352b15cb3dSCy Schubert @param eventcb_ptr if eventcb_ptr is nonnull, *eventcb_ptr is set to the 3362b15cb3dSCy Schubert current event callback for the bufferevent. 3372b15cb3dSCy Schubert @param cbarg_ptr if cbarg_ptr is nonnull, *cbarg_ptr is set to the current 3382b15cb3dSCy Schubert callback argument for the bufferevent. 3392b15cb3dSCy Schubert @see buffervent_setcb() 3402b15cb3dSCy Schubert */ 3412b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 3422b15cb3dSCy Schubert void bufferevent_getcb(struct bufferevent *bufev, 3432b15cb3dSCy Schubert bufferevent_data_cb *readcb_ptr, 3442b15cb3dSCy Schubert bufferevent_data_cb *writecb_ptr, 3452b15cb3dSCy Schubert bufferevent_event_cb *eventcb_ptr, 3462b15cb3dSCy Schubert void **cbarg_ptr); 3472b15cb3dSCy Schubert 3482b15cb3dSCy Schubert /** 3492b15cb3dSCy Schubert Changes the file descriptor on which the bufferevent operates. 3502b15cb3dSCy Schubert Not supported for all bufferevent types. 3512b15cb3dSCy Schubert 3522b15cb3dSCy Schubert @param bufev the bufferevent object for which to change the file descriptor 3532b15cb3dSCy Schubert @param fd the file descriptor to operate on 3542b15cb3dSCy Schubert */ 3552b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 3562b15cb3dSCy Schubert int bufferevent_setfd(struct bufferevent *bufev, evutil_socket_t fd); 3572b15cb3dSCy Schubert 3582b15cb3dSCy Schubert /** 3592b15cb3dSCy Schubert Returns the file descriptor associated with a bufferevent, or -1 if 3602b15cb3dSCy Schubert no file descriptor is associated with the bufferevent. 3612b15cb3dSCy Schubert */ 3622b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 3632b15cb3dSCy Schubert evutil_socket_t bufferevent_getfd(struct bufferevent *bufev); 3642b15cb3dSCy Schubert 3652b15cb3dSCy Schubert /** 3662b15cb3dSCy Schubert Returns the underlying bufferevent associated with a bufferevent (if 3672b15cb3dSCy Schubert the bufferevent is a wrapper), or NULL if there is no underlying bufferevent. 3682b15cb3dSCy Schubert */ 3692b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 3702b15cb3dSCy Schubert struct bufferevent *bufferevent_get_underlying(struct bufferevent *bufev); 3712b15cb3dSCy Schubert 3722b15cb3dSCy Schubert /** 3732b15cb3dSCy Schubert Write data to a bufferevent buffer. 3742b15cb3dSCy Schubert 3752b15cb3dSCy Schubert The bufferevent_write() function can be used to write data to the file 3762b15cb3dSCy Schubert descriptor. The data is appended to the output buffer and written to the 3772b15cb3dSCy Schubert descriptor automatically as it becomes available for writing. 3782b15cb3dSCy Schubert 3792b15cb3dSCy Schubert @param bufev the bufferevent to be written to 3802b15cb3dSCy Schubert @param data a pointer to the data to be written 3812b15cb3dSCy Schubert @param size the length of the data, in bytes 3822b15cb3dSCy Schubert @return 0 if successful, or -1 if an error occurred 3832b15cb3dSCy Schubert @see bufferevent_write_buffer() 3842b15cb3dSCy Schubert */ 3852b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 3862b15cb3dSCy Schubert int bufferevent_write(struct bufferevent *bufev, 3872b15cb3dSCy Schubert const void *data, size_t size); 3882b15cb3dSCy Schubert 3892b15cb3dSCy Schubert 3902b15cb3dSCy Schubert /** 3912b15cb3dSCy Schubert Write data from an evbuffer to a bufferevent buffer. The evbuffer is 3922b15cb3dSCy Schubert being drained as a result. 3932b15cb3dSCy Schubert 3942b15cb3dSCy Schubert @param bufev the bufferevent to be written to 3952b15cb3dSCy Schubert @param buf the evbuffer to be written 3962b15cb3dSCy Schubert @return 0 if successful, or -1 if an error occurred 3972b15cb3dSCy Schubert @see bufferevent_write() 3982b15cb3dSCy Schubert */ 3992b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4002b15cb3dSCy Schubert int bufferevent_write_buffer(struct bufferevent *bufev, struct evbuffer *buf); 4012b15cb3dSCy Schubert 4022b15cb3dSCy Schubert 4032b15cb3dSCy Schubert /** 4042b15cb3dSCy Schubert Read data from a bufferevent buffer. 4052b15cb3dSCy Schubert 4062b15cb3dSCy Schubert The bufferevent_read() function is used to read data from the input buffer. 4072b15cb3dSCy Schubert 4082b15cb3dSCy Schubert @param bufev the bufferevent to be read from 4092b15cb3dSCy Schubert @param data pointer to a buffer that will store the data 4102b15cb3dSCy Schubert @param size the size of the data buffer, in bytes 4112b15cb3dSCy Schubert @return the amount of data read, in bytes. 4122b15cb3dSCy Schubert */ 4132b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4142b15cb3dSCy Schubert size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size); 4152b15cb3dSCy Schubert 4162b15cb3dSCy Schubert /** 4172b15cb3dSCy Schubert Read data from a bufferevent buffer into an evbuffer. This avoids 4182b15cb3dSCy Schubert memory copies. 4192b15cb3dSCy Schubert 4202b15cb3dSCy Schubert @param bufev the bufferevent to be read from 4212b15cb3dSCy Schubert @param buf the evbuffer to which to add data 4222b15cb3dSCy Schubert @return 0 if successful, or -1 if an error occurred. 4232b15cb3dSCy Schubert */ 4242b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4252b15cb3dSCy Schubert int bufferevent_read_buffer(struct bufferevent *bufev, struct evbuffer *buf); 4262b15cb3dSCy Schubert 4272b15cb3dSCy Schubert /** 4282b15cb3dSCy Schubert Returns the input buffer. 4292b15cb3dSCy Schubert 4302b15cb3dSCy Schubert The user MUST NOT set the callback on this buffer. 4312b15cb3dSCy Schubert 4322b15cb3dSCy Schubert @param bufev the bufferevent from which to get the evbuffer 4332b15cb3dSCy Schubert @return the evbuffer object for the input buffer 4342b15cb3dSCy Schubert */ 4352b15cb3dSCy Schubert 4362b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4372b15cb3dSCy Schubert struct evbuffer *bufferevent_get_input(struct bufferevent *bufev); 4382b15cb3dSCy Schubert 4392b15cb3dSCy Schubert /** 4402b15cb3dSCy Schubert Returns the output buffer. 4412b15cb3dSCy Schubert 4422b15cb3dSCy Schubert The user MUST NOT set the callback on this buffer. 4432b15cb3dSCy Schubert 4442b15cb3dSCy Schubert When filters are being used, the filters need to be manually 4452b15cb3dSCy Schubert triggered if the output buffer was manipulated. 4462b15cb3dSCy Schubert 4472b15cb3dSCy Schubert @param bufev the bufferevent from which to get the evbuffer 4482b15cb3dSCy Schubert @return the evbuffer object for the output buffer 4492b15cb3dSCy Schubert */ 4502b15cb3dSCy Schubert 4512b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4522b15cb3dSCy Schubert struct evbuffer *bufferevent_get_output(struct bufferevent *bufev); 4532b15cb3dSCy Schubert 4542b15cb3dSCy Schubert /** 4552b15cb3dSCy Schubert Enable a bufferevent. 4562b15cb3dSCy Schubert 4572b15cb3dSCy Schubert @param bufev the bufferevent to be enabled 4582b15cb3dSCy Schubert @param event any combination of EV_READ | EV_WRITE. 4592b15cb3dSCy Schubert @return 0 if successful, or -1 if an error occurred 4602b15cb3dSCy Schubert @see bufferevent_disable() 4612b15cb3dSCy Schubert */ 4622b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4632b15cb3dSCy Schubert int bufferevent_enable(struct bufferevent *bufev, short event); 4642b15cb3dSCy Schubert 4652b15cb3dSCy Schubert /** 4662b15cb3dSCy Schubert Disable a bufferevent. 4672b15cb3dSCy Schubert 4682b15cb3dSCy Schubert @param bufev the bufferevent to be disabled 4692b15cb3dSCy Schubert @param event any combination of EV_READ | EV_WRITE. 4702b15cb3dSCy Schubert @return 0 if successful, or -1 if an error occurred 4712b15cb3dSCy Schubert @see bufferevent_enable() 4722b15cb3dSCy Schubert */ 4732b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4742b15cb3dSCy Schubert int bufferevent_disable(struct bufferevent *bufev, short event); 4752b15cb3dSCy Schubert 4762b15cb3dSCy Schubert /** 4772b15cb3dSCy Schubert Return the events that are enabled on a given bufferevent. 4782b15cb3dSCy Schubert 4792b15cb3dSCy Schubert @param bufev the bufferevent to inspect 4802b15cb3dSCy Schubert @return A combination of EV_READ | EV_WRITE 4812b15cb3dSCy Schubert */ 4822b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 4832b15cb3dSCy Schubert short bufferevent_get_enabled(struct bufferevent *bufev); 4842b15cb3dSCy Schubert 4852b15cb3dSCy Schubert /** 4862b15cb3dSCy Schubert Set the read and write timeout for a bufferevent. 4872b15cb3dSCy Schubert 4882b15cb3dSCy Schubert A bufferevent's timeout will fire the first time that the indicated 4892b15cb3dSCy Schubert amount of time has elapsed since a successful read or write operation, 4902b15cb3dSCy Schubert during which the bufferevent was trying to read or write. 4912b15cb3dSCy Schubert 4922b15cb3dSCy Schubert (In other words, if reading or writing is disabled, or if the 4932b15cb3dSCy Schubert bufferevent's read or write operation has been suspended because 494*a466cc55SCy Schubert there's no data to write, or not enough bandwidth, or so on, the 4952b15cb3dSCy Schubert timeout isn't active. The timeout only becomes active when we we're 4962b15cb3dSCy Schubert willing to actually read or write.) 4972b15cb3dSCy Schubert 4982b15cb3dSCy Schubert Calling bufferevent_enable or setting a timeout for a bufferevent 4992b15cb3dSCy Schubert whose timeout is already pending resets its timeout. 5002b15cb3dSCy Schubert 5012b15cb3dSCy Schubert If the timeout elapses, the corresponding operation (EV_READ or 5022b15cb3dSCy Schubert EV_WRITE) becomes disabled until you re-enable it again. The 5032b15cb3dSCy Schubert bufferevent's event callback is called with the 5042b15cb3dSCy Schubert BEV_EVENT_TIMEOUT|BEV_EVENT_READING or 5052b15cb3dSCy Schubert BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING. 5062b15cb3dSCy Schubert 5072b15cb3dSCy Schubert @param bufev the bufferevent to be modified 5082b15cb3dSCy Schubert @param timeout_read the read timeout, or NULL 5092b15cb3dSCy Schubert @param timeout_write the write timeout, or NULL 5102b15cb3dSCy Schubert */ 5112b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 5122b15cb3dSCy Schubert int bufferevent_set_timeouts(struct bufferevent *bufev, 5132b15cb3dSCy Schubert const struct timeval *timeout_read, const struct timeval *timeout_write); 5142b15cb3dSCy Schubert 5152b15cb3dSCy Schubert /** 5162b15cb3dSCy Schubert Sets the watermarks for read and write events. 5172b15cb3dSCy Schubert 5182b15cb3dSCy Schubert On input, a bufferevent does not invoke the user read callback unless 5192b15cb3dSCy Schubert there is at least low watermark data in the buffer. If the read buffer 5202b15cb3dSCy Schubert is beyond the high watermark, the bufferevent stops reading from the network. 521*a466cc55SCy Schubert But be aware that bufferevent input/read buffer can overrun high watermark 522*a466cc55SCy Schubert limit (typical example is openssl bufferevent), so you should not relay in 523*a466cc55SCy Schubert this. 5242b15cb3dSCy Schubert 5252b15cb3dSCy Schubert On output, the user write callback is invoked whenever the buffered data 5262b15cb3dSCy Schubert falls below the low watermark. Filters that write to this bufev will try 5272b15cb3dSCy Schubert not to write more bytes to this buffer than the high watermark would allow, 5282b15cb3dSCy Schubert except when flushing. 5292b15cb3dSCy Schubert 5302b15cb3dSCy Schubert @param bufev the bufferevent to be modified 5312b15cb3dSCy Schubert @param events EV_READ, EV_WRITE or both 5322b15cb3dSCy Schubert @param lowmark the lower watermark to set 5332b15cb3dSCy Schubert @param highmark the high watermark to set 5342b15cb3dSCy Schubert */ 5352b15cb3dSCy Schubert 5362b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 5372b15cb3dSCy Schubert void bufferevent_setwatermark(struct bufferevent *bufev, short events, 5382b15cb3dSCy Schubert size_t lowmark, size_t highmark); 5392b15cb3dSCy Schubert 5402b15cb3dSCy Schubert /** 541a25439b6SCy Schubert Retrieves the watermarks for read or write events. 542a25439b6SCy Schubert Returns non-zero if events contains not only EV_READ or EV_WRITE. 543a25439b6SCy Schubert Returns zero if events equal EV_READ or EV_WRITE 5442b15cb3dSCy Schubert 5452b15cb3dSCy Schubert @param bufev the bufferevent to be examined 5462b15cb3dSCy Schubert @param events EV_READ or EV_WRITE 5472b15cb3dSCy Schubert @param lowmark receives the lower watermark if not NULL 5482b15cb3dSCy Schubert @param highmark receives the high watermark if not NULL 5492b15cb3dSCy Schubert */ 5502b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 551a25439b6SCy Schubert int bufferevent_getwatermark(struct bufferevent *bufev, short events, 5522b15cb3dSCy Schubert size_t *lowmark, size_t *highmark); 5532b15cb3dSCy Schubert 5542b15cb3dSCy Schubert /** 5552b15cb3dSCy Schubert Acquire the lock on a bufferevent. Has no effect if locking was not 5562b15cb3dSCy Schubert enabled with BEV_OPT_THREADSAFE. 5572b15cb3dSCy Schubert */ 5582b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 5592b15cb3dSCy Schubert void bufferevent_lock(struct bufferevent *bufev); 5602b15cb3dSCy Schubert 5612b15cb3dSCy Schubert /** 5622b15cb3dSCy Schubert Release the lock on a bufferevent. Has no effect if locking was not 5632b15cb3dSCy Schubert enabled with BEV_OPT_THREADSAFE. 5642b15cb3dSCy Schubert */ 5652b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 5662b15cb3dSCy Schubert void bufferevent_unlock(struct bufferevent *bufev); 5672b15cb3dSCy Schubert 568*a466cc55SCy Schubert 569*a466cc55SCy Schubert /** 570*a466cc55SCy Schubert * Public interface to manually increase the reference count of a bufferevent 571*a466cc55SCy Schubert * this is useful in situations where a user may reference the bufferevent 572*a466cc55SCy Schubert * somewhere else (unknown to libevent) 573*a466cc55SCy Schubert * 574*a466cc55SCy Schubert * @param bufev the bufferevent to increase the refcount on 575*a466cc55SCy Schubert * 576*a466cc55SCy Schubert */ 577*a466cc55SCy Schubert EVENT2_EXPORT_SYMBOL 578*a466cc55SCy Schubert void bufferevent_incref(struct bufferevent *bufev); 579*a466cc55SCy Schubert 580*a466cc55SCy Schubert /** 581*a466cc55SCy Schubert * Public interface to manually decrement the reference count of a bufferevent 582*a466cc55SCy Schubert * 583*a466cc55SCy Schubert * Warning: make sure you know what you're doing. This is mainly used in 584*a466cc55SCy Schubert * conjunction with bufferevent_incref(). This will free up all data associated 585*a466cc55SCy Schubert * with a bufferevent if the reference count hits 0. 586*a466cc55SCy Schubert * 587*a466cc55SCy Schubert * @param bufev the bufferevent to decrement the refcount on 588*a466cc55SCy Schubert * 589*a466cc55SCy Schubert * @return 1 if the bufferevent was freed, otherwise 0 (still referenced) 590*a466cc55SCy Schubert */ 591*a466cc55SCy Schubert EVENT2_EXPORT_SYMBOL 592*a466cc55SCy Schubert int bufferevent_decref(struct bufferevent *bufev); 593*a466cc55SCy Schubert 5942b15cb3dSCy Schubert /** 5952b15cb3dSCy Schubert Flags that can be passed into filters to let them know how to 5962b15cb3dSCy Schubert deal with the incoming data. 5972b15cb3dSCy Schubert */ 5982b15cb3dSCy Schubert enum bufferevent_flush_mode { 5992b15cb3dSCy Schubert /** usually set when processing data */ 6002b15cb3dSCy Schubert BEV_NORMAL = 0, 6012b15cb3dSCy Schubert 6022b15cb3dSCy Schubert /** want to checkpoint all data sent. */ 6032b15cb3dSCy Schubert BEV_FLUSH = 1, 6042b15cb3dSCy Schubert 6052b15cb3dSCy Schubert /** encountered EOF on read or done sending data */ 6062b15cb3dSCy Schubert BEV_FINISHED = 2 6072b15cb3dSCy Schubert }; 6082b15cb3dSCy Schubert 6092b15cb3dSCy Schubert /** 6102b15cb3dSCy Schubert Triggers the bufferevent to produce more data if possible. 6112b15cb3dSCy Schubert 6122b15cb3dSCy Schubert @param bufev the bufferevent object 6132b15cb3dSCy Schubert @param iotype either EV_READ or EV_WRITE or both. 6142b15cb3dSCy Schubert @param mode either BEV_NORMAL or BEV_FLUSH or BEV_FINISHED 6152b15cb3dSCy Schubert @return -1 on failure, 0 if no data was produces, 1 if data was produced 6162b15cb3dSCy Schubert */ 6172b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 6182b15cb3dSCy Schubert int bufferevent_flush(struct bufferevent *bufev, 6192b15cb3dSCy Schubert short iotype, 6202b15cb3dSCy Schubert enum bufferevent_flush_mode mode); 6212b15cb3dSCy Schubert 6222b15cb3dSCy Schubert /** 6232b15cb3dSCy Schubert Flags for bufferevent_trigger(_event) that modify when and how to trigger 6242b15cb3dSCy Schubert the callback. 6252b15cb3dSCy Schubert */ 6262b15cb3dSCy Schubert enum bufferevent_trigger_options { 6272b15cb3dSCy Schubert /** trigger the callback regardless of the watermarks */ 6282b15cb3dSCy Schubert BEV_TRIG_IGNORE_WATERMARKS = (1<<16), 6292b15cb3dSCy Schubert 6302b15cb3dSCy Schubert /** defer even if the callbacks are not */ 631a25439b6SCy Schubert BEV_TRIG_DEFER_CALLBACKS = BEV_OPT_DEFER_CALLBACKS 6322b15cb3dSCy Schubert 6332b15cb3dSCy Schubert /* (Note: for internal reasons, these need to be disjoint from 6342b15cb3dSCy Schubert * bufferevent_options, except when they mean the same thing. */ 6352b15cb3dSCy Schubert }; 6362b15cb3dSCy Schubert 6372b15cb3dSCy Schubert /** 6382b15cb3dSCy Schubert Triggers bufferevent data callbacks. 6392b15cb3dSCy Schubert 6402b15cb3dSCy Schubert The function will honor watermarks unless options contain 6412b15cb3dSCy Schubert BEV_TRIG_IGNORE_WATERMARKS. If the options contain BEV_OPT_DEFER_CALLBACKS, 6422b15cb3dSCy Schubert the callbacks are deferred. 6432b15cb3dSCy Schubert 6442b15cb3dSCy Schubert @param bufev the bufferevent object 6452b15cb3dSCy Schubert @param iotype either EV_READ or EV_WRITE or both. 6462b15cb3dSCy Schubert @param options 6472b15cb3dSCy Schubert */ 6482b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 6492b15cb3dSCy Schubert void bufferevent_trigger(struct bufferevent *bufev, short iotype, 6502b15cb3dSCy Schubert int options); 6512b15cb3dSCy Schubert 6522b15cb3dSCy Schubert /** 6532b15cb3dSCy Schubert Triggers the bufferevent event callback. 6542b15cb3dSCy Schubert 6552b15cb3dSCy Schubert If the options contain BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred. 6562b15cb3dSCy Schubert 6572b15cb3dSCy Schubert @param bufev the bufferevent object 6582b15cb3dSCy Schubert @param what the flags to pass onto the event callback 6592b15cb3dSCy Schubert @param options 6602b15cb3dSCy Schubert */ 6612b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 6622b15cb3dSCy Schubert void bufferevent_trigger_event(struct bufferevent *bufev, short what, 6632b15cb3dSCy Schubert int options); 6642b15cb3dSCy Schubert 6652b15cb3dSCy Schubert /** 6662b15cb3dSCy Schubert @name Filtering support 6672b15cb3dSCy Schubert 6682b15cb3dSCy Schubert @{ 6692b15cb3dSCy Schubert */ 6702b15cb3dSCy Schubert /** 6712b15cb3dSCy Schubert Values that filters can return. 6722b15cb3dSCy Schubert */ 6732b15cb3dSCy Schubert enum bufferevent_filter_result { 6742b15cb3dSCy Schubert /** everything is okay */ 6752b15cb3dSCy Schubert BEV_OK = 0, 6762b15cb3dSCy Schubert 6772b15cb3dSCy Schubert /** the filter needs to read more data before output */ 6782b15cb3dSCy Schubert BEV_NEED_MORE = 1, 6792b15cb3dSCy Schubert 6802b15cb3dSCy Schubert /** the filter encountered a critical error, no further data 6812b15cb3dSCy Schubert can be processed. */ 6822b15cb3dSCy Schubert BEV_ERROR = 2 6832b15cb3dSCy Schubert }; 6842b15cb3dSCy Schubert 6852b15cb3dSCy Schubert /** A callback function to implement a filter for a bufferevent. 6862b15cb3dSCy Schubert 6872b15cb3dSCy Schubert @param src An evbuffer to drain data from. 6882b15cb3dSCy Schubert @param dst An evbuffer to add data to. 6892b15cb3dSCy Schubert @param limit A suggested upper bound of bytes to write to dst. 6902b15cb3dSCy Schubert The filter may ignore this value, but doing so means that 6912b15cb3dSCy Schubert it will overflow the high-water mark associated with dst. 6922b15cb3dSCy Schubert -1 means "no limit". 6932b15cb3dSCy Schubert @param mode Whether we should write data as may be convenient 6942b15cb3dSCy Schubert (BEV_NORMAL), or flush as much data as we can (BEV_FLUSH), 6952b15cb3dSCy Schubert or flush as much as we can, possibly including an end-of-stream 6962b15cb3dSCy Schubert marker (BEV_FINISH). 6972b15cb3dSCy Schubert @param ctx A user-supplied pointer. 6982b15cb3dSCy Schubert 6992b15cb3dSCy Schubert @return BEV_OK if we wrote some data; BEV_NEED_MORE if we can't 7002b15cb3dSCy Schubert produce any more output until we get some input; and BEV_ERROR 7012b15cb3dSCy Schubert on an error. 7022b15cb3dSCy Schubert */ 7032b15cb3dSCy Schubert typedef enum bufferevent_filter_result (*bufferevent_filter_cb)( 7042b15cb3dSCy Schubert struct evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit, 7052b15cb3dSCy Schubert enum bufferevent_flush_mode mode, void *ctx); 7062b15cb3dSCy Schubert 7072b15cb3dSCy Schubert /** 7082b15cb3dSCy Schubert Allocate a new filtering bufferevent on top of an existing bufferevent. 7092b15cb3dSCy Schubert 7102b15cb3dSCy Schubert @param underlying the underlying bufferevent. 7112b15cb3dSCy Schubert @param input_filter The filter to apply to data we read from the underlying 7122b15cb3dSCy Schubert bufferevent 7132b15cb3dSCy Schubert @param output_filter The filer to apply to data we write to the underlying 7142b15cb3dSCy Schubert bufferevent 7152b15cb3dSCy Schubert @param options A bitfield of bufferevent options. 7162b15cb3dSCy Schubert @param free_context A function to use to free the filter context when 7172b15cb3dSCy Schubert this bufferevent is freed. 7182b15cb3dSCy Schubert @param ctx A context pointer to pass to the filter functions. 7192b15cb3dSCy Schubert */ 7202b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 7212b15cb3dSCy Schubert struct bufferevent * 7222b15cb3dSCy Schubert bufferevent_filter_new(struct bufferevent *underlying, 7232b15cb3dSCy Schubert bufferevent_filter_cb input_filter, 7242b15cb3dSCy Schubert bufferevent_filter_cb output_filter, 7252b15cb3dSCy Schubert int options, 7262b15cb3dSCy Schubert void (*free_context)(void *), 7272b15cb3dSCy Schubert void *ctx); 7282b15cb3dSCy Schubert /**@}*/ 7292b15cb3dSCy Schubert 7302b15cb3dSCy Schubert /** 7312b15cb3dSCy Schubert Allocate a pair of linked bufferevents. The bufferevents behave as would 7322b15cb3dSCy Schubert two bufferevent_sock instances connected to opposite ends of a 7332b15cb3dSCy Schubert socketpair(), except that no internal socketpair is allocated. 7342b15cb3dSCy Schubert 7352b15cb3dSCy Schubert @param base The event base to associate with the socketpair. 7362b15cb3dSCy Schubert @param options A set of options for this bufferevent 7372b15cb3dSCy Schubert @param pair A pointer to an array to hold the two new bufferevent objects. 7382b15cb3dSCy Schubert @return 0 on success, -1 on failure. 7392b15cb3dSCy Schubert */ 7402b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 7412b15cb3dSCy Schubert int bufferevent_pair_new(struct event_base *base, int options, 7422b15cb3dSCy Schubert struct bufferevent *pair[2]); 7432b15cb3dSCy Schubert 7442b15cb3dSCy Schubert /** 7452b15cb3dSCy Schubert Given one bufferevent returned by bufferevent_pair_new(), returns the 7462b15cb3dSCy Schubert other one if it still exists. Otherwise returns NULL. 7472b15cb3dSCy Schubert */ 7482b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 7492b15cb3dSCy Schubert struct bufferevent *bufferevent_pair_get_partner(struct bufferevent *bev); 7502b15cb3dSCy Schubert 7512b15cb3dSCy Schubert /** 7522b15cb3dSCy Schubert Abstract type used to configure rate-limiting on a bufferevent or a group 7532b15cb3dSCy Schubert of bufferevents. 7542b15cb3dSCy Schubert */ 7552b15cb3dSCy Schubert struct ev_token_bucket_cfg; 7562b15cb3dSCy Schubert 7572b15cb3dSCy Schubert /** 7582b15cb3dSCy Schubert A group of bufferevents which are configured to respect the same rate 7592b15cb3dSCy Schubert limit. 7602b15cb3dSCy Schubert */ 7612b15cb3dSCy Schubert struct bufferevent_rate_limit_group; 7622b15cb3dSCy Schubert 7632b15cb3dSCy Schubert /** Maximum configurable rate- or burst-limit. */ 7642b15cb3dSCy Schubert #define EV_RATE_LIMIT_MAX EV_SSIZE_MAX 7652b15cb3dSCy Schubert 7662b15cb3dSCy Schubert /** 7672b15cb3dSCy Schubert Initialize and return a new object to configure the rate-limiting behavior 7682b15cb3dSCy Schubert of bufferevents. 7692b15cb3dSCy Schubert 7702b15cb3dSCy Schubert @param read_rate The maximum number of bytes to read per tick on 7712b15cb3dSCy Schubert average. 7722b15cb3dSCy Schubert @param read_burst The maximum number of bytes to read in any single tick. 7732b15cb3dSCy Schubert @param write_rate The maximum number of bytes to write per tick on 7742b15cb3dSCy Schubert average. 7752b15cb3dSCy Schubert @param write_burst The maximum number of bytes to write in any single tick. 7762b15cb3dSCy Schubert @param tick_len The length of a single tick. Defaults to one second. 7772b15cb3dSCy Schubert Any fractions of a millisecond are ignored. 7782b15cb3dSCy Schubert 7792b15cb3dSCy Schubert Note that all rate-limits hare are currently best-effort: future versions 7802b15cb3dSCy Schubert of Libevent may implement them more tightly. 7812b15cb3dSCy Schubert */ 7822b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 7832b15cb3dSCy Schubert struct ev_token_bucket_cfg *ev_token_bucket_cfg_new( 7842b15cb3dSCy Schubert size_t read_rate, size_t read_burst, 7852b15cb3dSCy Schubert size_t write_rate, size_t write_burst, 7862b15cb3dSCy Schubert const struct timeval *tick_len); 7872b15cb3dSCy Schubert 7882b15cb3dSCy Schubert /** Free all storage held in 'cfg'. 7892b15cb3dSCy Schubert 7902b15cb3dSCy Schubert Note: 'cfg' is not currently reference-counted; it is not safe to free it 7912b15cb3dSCy Schubert until no bufferevent is using it. 7922b15cb3dSCy Schubert */ 7932b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 7942b15cb3dSCy Schubert void ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg); 7952b15cb3dSCy Schubert 7962b15cb3dSCy Schubert /** 7972b15cb3dSCy Schubert Set the rate-limit of a the bufferevent 'bev' to the one specified in 7982b15cb3dSCy Schubert 'cfg'. If 'cfg' is NULL, disable any per-bufferevent rate-limiting on 7992b15cb3dSCy Schubert 'bev'. 8002b15cb3dSCy Schubert 8012b15cb3dSCy Schubert Note that only some bufferevent types currently respect rate-limiting. 8022b15cb3dSCy Schubert They are: socket-based bufferevents (normal and IOCP-based), and SSL-based 8032b15cb3dSCy Schubert bufferevents. 8042b15cb3dSCy Schubert 805*a466cc55SCy Schubert Return 0 on success, -1 on failure. 8062b15cb3dSCy Schubert */ 8072b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8082b15cb3dSCy Schubert int bufferevent_set_rate_limit(struct bufferevent *bev, 8092b15cb3dSCy Schubert struct ev_token_bucket_cfg *cfg); 8102b15cb3dSCy Schubert 8112b15cb3dSCy Schubert /** 8122b15cb3dSCy Schubert Create a new rate-limit group for bufferevents. A rate-limit group 8132b15cb3dSCy Schubert constrains the maximum number of bytes sent and received, in toto, 8142b15cb3dSCy Schubert by all of its bufferevents. 8152b15cb3dSCy Schubert 8162b15cb3dSCy Schubert @param base An event_base to run any necessary timeouts for the group. 8172b15cb3dSCy Schubert Note that all bufferevents in the group do not necessarily need to share 8182b15cb3dSCy Schubert this event_base. 8192b15cb3dSCy Schubert @param cfg The rate-limit for this group. 8202b15cb3dSCy Schubert 8212b15cb3dSCy Schubert Note that all rate-limits hare are currently best-effort: future versions 8222b15cb3dSCy Schubert of Libevent may implement them more tightly. 8232b15cb3dSCy Schubert 8242b15cb3dSCy Schubert Note also that only some bufferevent types currently respect rate-limiting. 8252b15cb3dSCy Schubert They are: socket-based bufferevents (normal and IOCP-based), and SSL-based 8262b15cb3dSCy Schubert bufferevents. 8272b15cb3dSCy Schubert */ 8282b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8292b15cb3dSCy Schubert struct bufferevent_rate_limit_group *bufferevent_rate_limit_group_new( 8302b15cb3dSCy Schubert struct event_base *base, 8312b15cb3dSCy Schubert const struct ev_token_bucket_cfg *cfg); 8322b15cb3dSCy Schubert /** 8332b15cb3dSCy Schubert Change the rate-limiting settings for a given rate-limiting group. 8342b15cb3dSCy Schubert 8352b15cb3dSCy Schubert Return 0 on success, -1 on failure. 8362b15cb3dSCy Schubert */ 8372b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8382b15cb3dSCy Schubert int bufferevent_rate_limit_group_set_cfg( 8392b15cb3dSCy Schubert struct bufferevent_rate_limit_group *, 8402b15cb3dSCy Schubert const struct ev_token_bucket_cfg *); 8412b15cb3dSCy Schubert 8422b15cb3dSCy Schubert /** 8432b15cb3dSCy Schubert Change the smallest quantum we're willing to allocate to any single 8442b15cb3dSCy Schubert bufferevent in a group for reading or writing at a time. 8452b15cb3dSCy Schubert 8462b15cb3dSCy Schubert The rationale is that, because of TCP/IP protocol overheads and kernel 8472b15cb3dSCy Schubert behavior, if a rate-limiting group is so tight on bandwidth that you're 8482b15cb3dSCy Schubert only willing to send 1 byte per tick per bufferevent, you might instead 8492b15cb3dSCy Schubert want to batch up the reads and writes so that you send N bytes per 8502b15cb3dSCy Schubert 1/N of the bufferevents (chosen at random) each tick, so you still wind 8512b15cb3dSCy Schubert up send 1 byte per tick per bufferevent on average, but you don't send 8522b15cb3dSCy Schubert so many tiny packets. 8532b15cb3dSCy Schubert 8542b15cb3dSCy Schubert The default min-share is currently 64 bytes. 8552b15cb3dSCy Schubert 856*a466cc55SCy Schubert Returns 0 on success, -1 on failure. 8572b15cb3dSCy Schubert */ 8582b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8592b15cb3dSCy Schubert int bufferevent_rate_limit_group_set_min_share( 8602b15cb3dSCy Schubert struct bufferevent_rate_limit_group *, size_t); 8612b15cb3dSCy Schubert 8622b15cb3dSCy Schubert /** 8632b15cb3dSCy Schubert Free a rate-limiting group. The group must have no members when 8642b15cb3dSCy Schubert this function is called. 8652b15cb3dSCy Schubert */ 8662b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8672b15cb3dSCy Schubert void bufferevent_rate_limit_group_free(struct bufferevent_rate_limit_group *); 8682b15cb3dSCy Schubert 8692b15cb3dSCy Schubert /** 8702b15cb3dSCy Schubert Add 'bev' to the list of bufferevents whose aggregate reading and writing 8712b15cb3dSCy Schubert is restricted by 'g'. If 'g' is NULL, remove 'bev' from its current group. 8722b15cb3dSCy Schubert 8732b15cb3dSCy Schubert A bufferevent may belong to no more than one rate-limit group at a time. 8742b15cb3dSCy Schubert If 'bev' is already a member of a group, it will be removed from its old 8752b15cb3dSCy Schubert group before being added to 'g'. 8762b15cb3dSCy Schubert 8772b15cb3dSCy Schubert Return 0 on success and -1 on failure. 8782b15cb3dSCy Schubert */ 8792b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8802b15cb3dSCy Schubert int bufferevent_add_to_rate_limit_group(struct bufferevent *bev, 8812b15cb3dSCy Schubert struct bufferevent_rate_limit_group *g); 8822b15cb3dSCy Schubert 8832b15cb3dSCy Schubert /** Remove 'bev' from its current rate-limit group (if any). */ 8842b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8852b15cb3dSCy Schubert int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev); 8862b15cb3dSCy Schubert 8872b15cb3dSCy Schubert /** 8882b15cb3dSCy Schubert Set the size limit for single read operation. 8892b15cb3dSCy Schubert 8902b15cb3dSCy Schubert Set to 0 for a reasonable default. 8912b15cb3dSCy Schubert 8922b15cb3dSCy Schubert Return 0 on success and -1 on failure. 8932b15cb3dSCy Schubert */ 8942b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 8952b15cb3dSCy Schubert int bufferevent_set_max_single_read(struct bufferevent *bev, size_t size); 8962b15cb3dSCy Schubert 8972b15cb3dSCy Schubert /** 8982b15cb3dSCy Schubert Set the size limit for single write operation. 8992b15cb3dSCy Schubert 9002b15cb3dSCy Schubert Set to 0 for a reasonable default. 9012b15cb3dSCy Schubert 9022b15cb3dSCy Schubert Return 0 on success and -1 on failure. 9032b15cb3dSCy Schubert */ 9042b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9052b15cb3dSCy Schubert int bufferevent_set_max_single_write(struct bufferevent *bev, size_t size); 9062b15cb3dSCy Schubert 9072b15cb3dSCy Schubert /** Get the current size limit for single read operation. */ 9082b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9092b15cb3dSCy Schubert ev_ssize_t bufferevent_get_max_single_read(struct bufferevent *bev); 9102b15cb3dSCy Schubert 9112b15cb3dSCy Schubert /** Get the current size limit for single write operation. */ 9122b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9132b15cb3dSCy Schubert ev_ssize_t bufferevent_get_max_single_write(struct bufferevent *bev); 9142b15cb3dSCy Schubert 9152b15cb3dSCy Schubert /** 9162b15cb3dSCy Schubert @name Rate limit inspection 9172b15cb3dSCy Schubert 9182b15cb3dSCy Schubert Return the current read or write bucket size for a bufferevent. 9192b15cb3dSCy Schubert If it is not configured with a per-bufferevent ratelimit, return 9202b15cb3dSCy Schubert EV_SSIZE_MAX. This function does not inspect the group limit, if any. 9212b15cb3dSCy Schubert Note that it can return a negative value if the bufferevent has been 9222b15cb3dSCy Schubert made to read or write more than its limit. 9232b15cb3dSCy Schubert 9242b15cb3dSCy Schubert @{ 9252b15cb3dSCy Schubert */ 9262b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9272b15cb3dSCy Schubert ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev); 9282b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9292b15cb3dSCy Schubert ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev); 9302b15cb3dSCy Schubert /*@}*/ 9312b15cb3dSCy Schubert 9322b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9332b15cb3dSCy Schubert ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev); 9342b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9352b15cb3dSCy Schubert ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev); 9362b15cb3dSCy Schubert 9372b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9382b15cb3dSCy Schubert const struct ev_token_bucket_cfg *bufferevent_get_token_bucket_cfg(const struct bufferevent * bev); 9392b15cb3dSCy Schubert 9402b15cb3dSCy Schubert /** 9412b15cb3dSCy Schubert @name Group Rate limit inspection 9422b15cb3dSCy Schubert 9432b15cb3dSCy Schubert Return the read or write bucket size for a bufferevent rate limit 9442b15cb3dSCy Schubert group. Note that it can return a negative value if bufferevents in 9452b15cb3dSCy Schubert the group have been made to read or write more than their limits. 9462b15cb3dSCy Schubert 9472b15cb3dSCy Schubert @{ 9482b15cb3dSCy Schubert */ 9492b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9502b15cb3dSCy Schubert ev_ssize_t bufferevent_rate_limit_group_get_read_limit( 9512b15cb3dSCy Schubert struct bufferevent_rate_limit_group *); 9522b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9532b15cb3dSCy Schubert ev_ssize_t bufferevent_rate_limit_group_get_write_limit( 9542b15cb3dSCy Schubert struct bufferevent_rate_limit_group *); 9552b15cb3dSCy Schubert /*@}*/ 9562b15cb3dSCy Schubert 9572b15cb3dSCy Schubert /** 9582b15cb3dSCy Schubert @name Rate limit manipulation 9592b15cb3dSCy Schubert 9602b15cb3dSCy Schubert Subtract a number of bytes from a bufferevent's read or write bucket. 9612b15cb3dSCy Schubert The decrement value can be negative, if you want to manually refill 9622b15cb3dSCy Schubert the bucket. If the change puts the bucket above or below zero, the 9632b15cb3dSCy Schubert bufferevent will resume or suspend reading writing as appropriate. 9642b15cb3dSCy Schubert These functions make no change in the buckets for the bufferevent's 9652b15cb3dSCy Schubert group, if any. 9662b15cb3dSCy Schubert 9672b15cb3dSCy Schubert Returns 0 on success, -1 on internal error. 9682b15cb3dSCy Schubert 9692b15cb3dSCy Schubert @{ 9702b15cb3dSCy Schubert */ 9712b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9722b15cb3dSCy Schubert int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr); 9732b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9742b15cb3dSCy Schubert int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr); 9752b15cb3dSCy Schubert /*@}*/ 9762b15cb3dSCy Schubert 9772b15cb3dSCy Schubert /** 9782b15cb3dSCy Schubert @name Group rate limit manipulation 9792b15cb3dSCy Schubert 9802b15cb3dSCy Schubert Subtract a number of bytes from a bufferevent rate-limiting group's 9812b15cb3dSCy Schubert read or write bucket. The decrement value can be negative, if you 9822b15cb3dSCy Schubert want to manually refill the bucket. If the change puts the bucket 9832b15cb3dSCy Schubert above or below zero, the bufferevents in the group will resume or 9842b15cb3dSCy Schubert suspend reading writing as appropriate. 9852b15cb3dSCy Schubert 9862b15cb3dSCy Schubert Returns 0 on success, -1 on internal error. 9872b15cb3dSCy Schubert 9882b15cb3dSCy Schubert @{ 9892b15cb3dSCy Schubert */ 9902b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9912b15cb3dSCy Schubert int bufferevent_rate_limit_group_decrement_read( 9922b15cb3dSCy Schubert struct bufferevent_rate_limit_group *, ev_ssize_t); 9932b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 9942b15cb3dSCy Schubert int bufferevent_rate_limit_group_decrement_write( 9952b15cb3dSCy Schubert struct bufferevent_rate_limit_group *, ev_ssize_t); 9962b15cb3dSCy Schubert /*@}*/ 9972b15cb3dSCy Schubert 9982b15cb3dSCy Schubert 9992b15cb3dSCy Schubert /** 10002b15cb3dSCy Schubert * Inspect the total bytes read/written on a group. 10012b15cb3dSCy Schubert * 10022b15cb3dSCy Schubert * Set the variable pointed to by total_read_out to the total number of bytes 10032b15cb3dSCy Schubert * ever read on grp, and the variable pointed to by total_written_out to the 10042b15cb3dSCy Schubert * total number of bytes ever written on grp. */ 10052b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 10062b15cb3dSCy Schubert void bufferevent_rate_limit_group_get_totals( 10072b15cb3dSCy Schubert struct bufferevent_rate_limit_group *grp, 10082b15cb3dSCy Schubert ev_uint64_t *total_read_out, ev_uint64_t *total_written_out); 10092b15cb3dSCy Schubert 10102b15cb3dSCy Schubert /** 10112b15cb3dSCy Schubert * Reset the total bytes read/written on a group. 10122b15cb3dSCy Schubert * 10132b15cb3dSCy Schubert * Reset the number of bytes read or written on grp as given by 10142b15cb3dSCy Schubert * bufferevent_rate_limit_group_reset_totals(). */ 10152b15cb3dSCy Schubert EVENT2_EXPORT_SYMBOL 10162b15cb3dSCy Schubert void 10172b15cb3dSCy Schubert bufferevent_rate_limit_group_reset_totals( 10182b15cb3dSCy Schubert struct bufferevent_rate_limit_group *grp); 10192b15cb3dSCy Schubert 10202b15cb3dSCy Schubert #ifdef __cplusplus 10212b15cb3dSCy Schubert } 10222b15cb3dSCy Schubert #endif 10232b15cb3dSCy Schubert 10242b15cb3dSCy Schubert #endif /* EVENT2_BUFFEREVENT_H_INCLUDED_ */ 1025