1/* 2 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. The name of the author may not be used to endorse or promote products 13 * derived from this software without specific prior written permission. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 */ 26#ifndef _EVENT2_BUFFER_H_ 27#define _EVENT2_BUFFER_H_ 28 29/** @file event2/buffer.h 30 31 Functions for buffering data for network sending or receiving. 32 33 An evbuffer can be used for preparing data before sending it to 34 the network or conversely for reading data from the network. 35 Evbuffers try to avoid memory copies as much as possible. As a 36 result, evbuffers can be used to pass data around without actually 37 incurring the overhead of copying the data. 38 39 A new evbuffer can be allocated with evbuffer_new(), and can be 40 freed with evbuffer_free(). Most users will be using evbuffers via 41 the bufferevent interface. To access a bufferevent's evbuffers, use 42 bufferevent_get_input() and bufferevent_get_output(). 43 44 There are several guidelines for using evbuffers. 45 46 - if you already know how much data you are going to add as a result 47 of calling evbuffer_add() multiple times, it makes sense to use 48 evbuffer_expand() first to make sure that enough memory is allocated 49 before hand. 50 51 - evbuffer_add_buffer() adds the contents of one buffer to the other 52 without incurring any unnecessary memory copies. 53 54 - evbuffer_add() and evbuffer_add_buffer() do not mix very well: 55 if you use them, you will wind up with fragmented memory in your 56 buffer. 57 58 - For high-performance code, you may want to avoid copying data into and out 59 of buffers. You can skip the copy step by using 60 evbuffer_reserve_space()/evbuffer_commit_space() when writing into a 61 buffer, and evbuffer_peek() when reading. 62 63 In Libevent 2.0 and later, evbuffers are represented using a linked 64 list of memory chunks, with pointers to the first and last chunk in 65 the chain. 66 67 As the contents of an evbuffer can be stored in multiple different 68 memory blocks, it cannot be accessed directly. Instead, evbuffer_pullup() 69 can be used to force a specified number of bytes to be contiguous. This 70 will cause memory reallocation and memory copies if the data is split 71 across multiple blocks. It is more efficient, however, to use 72 evbuffer_peek() if you don't require that the memory to be contiguous. 73 */ 74 75#ifdef __cplusplus 76extern "C" { 77#endif 78 79#include <event2/event-config.h> 80#include <stdarg.h> 81#ifdef _EVENT_HAVE_SYS_TYPES_H 82#include <sys/types.h> 83#endif 84#ifdef _EVENT_HAVE_SYS_UIO_H 85#include <sys/uio.h> 86#endif 87#include <event2/util.h> 88 89/** 90 An evbuffer is an opaque data type for efficiently buffering data to be 91 sent or received on the network. 92 93 @see event2/event.h for more information 94*/ 95struct evbuffer 96#ifdef _EVENT_IN_DOXYGEN 97{} 98#endif 99; 100 101/** 102 Pointer to a position within an evbuffer. 103 104 Used when repeatedly searching through a buffer. Calling any function 105 that modifies or re-packs the buffer contents may invalidate all 106 evbuffer_ptrs for that buffer. Do not modify these values except with 107 evbuffer_ptr_set. 108 */ 109struct evbuffer_ptr { 110 ev_ssize_t pos; 111 112 /* Do not alter the values of fields. */ 113 struct { 114 void *chain; 115 size_t pos_in_chain; 116 } _internal; 117}; 118 119/** Describes a single extent of memory inside an evbuffer. Used for 120 direct-access functions. 121 122 @see evbuffer_reserve_space, evbuffer_commit_space, evbuffer_peek 123 */ 124#ifdef _EVENT_HAVE_SYS_UIO_H 125#define evbuffer_iovec iovec 126/* Internal use -- defined only if we are using the native struct iovec */ 127#define _EVBUFFER_IOVEC_IS_NATIVE 128#else 129struct evbuffer_iovec { 130 /** The start of the extent of memory. */ 131 void *iov_base; 132 /** The length of the extent of memory. */ 133 size_t iov_len; 134}; 135#endif 136 137/** 138 Allocate storage for a new evbuffer. 139 140 @return a pointer to a newly allocated evbuffer struct, or NULL if an error 141 occurred 142 */ 143struct evbuffer *evbuffer_new(void); 144/** 145 Deallocate storage for an evbuffer. 146 147 @param buf pointer to the evbuffer to be freed 148 */ 149void evbuffer_free(struct evbuffer *buf); 150 151/** 152 Enable locking on an evbuffer so that it can safely be used by multiple 153 threads at the same time. 154 155 NOTE: when locking is enabled, the lock will be held when callbacks are 156 invoked. This could result in deadlock if you aren't careful. Plan 157 accordingly! 158 159 @param buf An evbuffer to make lockable. 160 @param lock A lock object, or NULL if we should allocate our own. 161 @return 0 on success, -1 on failure. 162 */ 163int evbuffer_enable_locking(struct evbuffer *buf, void *lock); 164 165/** 166 Acquire the lock on an evbuffer. Has no effect if locking was not enabled 167 with evbuffer_enable_locking. 168*/ 169void evbuffer_lock(struct evbuffer *buf); 170 171/** 172 Release the lock on an evbuffer. Has no effect if locking was not enabled 173 with evbuffer_enable_locking. 174*/ 175void evbuffer_unlock(struct evbuffer *buf); 176 177 178/** If this flag is set, then we will not use evbuffer_peek(), 179 * evbuffer_remove(), evbuffer_remove_buffer(), and so on to read bytes 180 * from this buffer: we'll only take bytes out of this buffer by 181 * writing them to the network (as with evbuffer_write_atmost), by 182 * removing them without observing them (as with evbuffer_drain), 183 * or by copying them all out at once (as with evbuffer_add_buffer). 184 * 185 * Using this option allows the implementation to use sendfile-based 186 * operations for evbuffer_add_file(); see that function for more 187 * information. 188 * 189 * This flag is on by default for bufferevents that can take advantage 190 * of it; you should never actually need to set it on a bufferevent's 191 * output buffer. 192 */ 193#define EVBUFFER_FLAG_DRAINS_TO_FD 1 194 195/** Change the flags that are set for an evbuffer by adding more. 196 * 197 * @param buffer the evbuffer that the callback is watching. 198 * @param cb the callback whose status we want to change. 199 * @param flags One or more EVBUFFER_FLAG_* options 200 * @return 0 on success, -1 on failure. 201 */ 202int evbuffer_set_flags(struct evbuffer *buf, ev_uint64_t flags); 203/** Change the flags that are set for an evbuffer by removing some. 204 * 205 * @param buffer the evbuffer that the callback is watching. 206 * @param cb the callback whose status we want to change. 207 * @param flags One or more EVBUFFER_FLAG_* options 208 * @return 0 on success, -1 on failure. 209 */ 210int evbuffer_clear_flags(struct evbuffer *buf, ev_uint64_t flags); 211 212/** 213 Returns the total number of bytes stored in the evbuffer 214 215 @param buf pointer to the evbuffer 216 @return the number of bytes stored in the evbuffer 217*/ 218size_t evbuffer_get_length(const struct evbuffer *buf); 219 220/** 221 Returns the number of contiguous available bytes in the first buffer chain. 222 223 This is useful when processing data that might be split into multiple 224 chains, or that might all be in the first chain. Calls to 225 evbuffer_pullup() that cause reallocation and copying of data can thus be 226 avoided. 227 228 @param buf pointer to the evbuffer 229 @return 0 if no data is available, otherwise the number of available bytes 230 in the first buffer chain. 231*/ 232size_t evbuffer_get_contiguous_space(const struct evbuffer *buf); 233 234/** 235 Expands the available space in an evbuffer. 236 237 Expands the available space in the evbuffer to at least datlen, so that 238 appending datlen additional bytes will not require any new allocations. 239 240 @param buf the evbuffer to be expanded 241 @param datlen the new minimum length requirement 242 @return 0 if successful, or -1 if an error occurred 243*/ 244int evbuffer_expand(struct evbuffer *buf, size_t datlen); 245 246/** 247 Reserves space in the last chain or chains of an evbuffer. 248 249 Makes space available in the last chain or chains of an evbuffer that can 250 be arbitrarily written to by a user. The space does not become 251 available for reading until it has been committed with 252 evbuffer_commit_space(). 253 254 The space is made available as one or more extents, represented by 255 an initial pointer and a length. You can force the memory to be 256 available as only one extent. Allowing more extents, however, makes the 257 function more efficient. 258 259 Multiple subsequent calls to this function will make the same space 260 available until evbuffer_commit_space() has been called. 261 262 It is an error to do anything that moves around the buffer's internal 263 memory structures before committing the space. 264 265 NOTE: The code currently does not ever use more than two extents. 266 This may change in future versions. 267 268 @param buf the evbuffer in which to reserve space. 269 @param size how much space to make available, at minimum. The 270 total length of the extents may be greater than the requested 271 length. 272 @param vec an array of one or more evbuffer_iovec structures to 273 hold pointers to the reserved extents of memory. 274 @param n_vec The length of the vec array. Must be at least 1; 275 2 is more efficient. 276 @return the number of provided extents, or -1 on error. 277 @see evbuffer_commit_space() 278*/ 279int 280evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size, 281 struct evbuffer_iovec *vec, int n_vec); 282 283/** 284 Commits previously reserved space. 285 286 Commits some of the space previously reserved with 287 evbuffer_reserve_space(). It then becomes available for reading. 288 289 This function may return an error if the pointer in the extents do 290 not match those returned from evbuffer_reserve_space, or if data 291 has been added to the buffer since the space was reserved. 292 293 If you want to commit less data than you got reserved space for, 294 modify the iov_len pointer of the appropriate extent to a smaller 295 value. Note that you may have received more space than you 296 requested if it was available! 297 298 @param buf the evbuffer in which to reserve space. 299 @param vec one or two extents returned by evbuffer_reserve_space. 300 @param n_vecs the number of extents. 301 @return 0 on success, -1 on error 302 @see evbuffer_reserve_space() 303*/ 304int evbuffer_commit_space(struct evbuffer *buf, 305 struct evbuffer_iovec *vec, int n_vecs); 306 307/** 308 Append data to the end of an evbuffer. 309 310 @param buf the evbuffer to be appended to 311 @param data pointer to the beginning of the data buffer 312 @param datlen the number of bytes to be copied from the data buffer 313 @return 0 on success, -1 on failure. 314 */ 315int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen); 316 317 318/** 319 Read data from an evbuffer and drain the bytes read. 320 321 If more bytes are requested than are available in the evbuffer, we 322 only extract as many bytes as were available. 323 324 @param buf the evbuffer to be read from 325 @param data the destination buffer to store the result 326 @param datlen the maximum size of the destination buffer 327 @return the number of bytes read, or -1 if we can't drain the buffer. 328 */ 329int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen); 330 331/** 332 Read data from an evbuffer, and leave the buffer unchanged. 333 334 If more bytes are requested than are available in the evbuffer, we 335 only extract as many bytes as were available. 336 337 @param buf the evbuffer to be read from 338 @param data_out the destination buffer to store the result 339 @param datlen the maximum size of the destination buffer 340 @return the number of bytes read, or -1 if we can't drain the buffer. 341 */ 342ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen); 343 344/** 345 Read data from an evbuffer into another evbuffer, draining 346 the bytes from the source buffer. This function avoids copy 347 operations to the extent possible. 348 349 If more bytes are requested than are available in src, the src 350 buffer is drained completely. 351 352 @param src the evbuffer to be read from 353 @param dst the destination evbuffer to store the result into 354 @param datlen the maximum numbers of bytes to transfer 355 @return the number of bytes read 356 */ 357int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst, 358 size_t datlen); 359 360/** Used to tell evbuffer_readln what kind of line-ending to look for. 361 */ 362enum evbuffer_eol_style { 363 /** Any sequence of CR and LF characters is acceptable as an 364 * EOL. 365 * 366 * Note that this style can produce ambiguous results: the 367 * sequence "CRLF" will be treated as a single EOL if it is 368 * all in the buffer at once, but if you first read a CR from 369 * the network and later read an LF from the network, it will 370 * be treated as two EOLs. 371 */ 372 EVBUFFER_EOL_ANY, 373 /** An EOL is an LF, optionally preceded by a CR. This style is 374 * most useful for implementing text-based internet protocols. */ 375 EVBUFFER_EOL_CRLF, 376 /** An EOL is a CR followed by an LF. */ 377 EVBUFFER_EOL_CRLF_STRICT, 378 /** An EOL is a LF. */ 379 EVBUFFER_EOL_LF 380}; 381 382/** 383 * Read a single line from an evbuffer. 384 * 385 * Reads a line terminated by an EOL as determined by the evbuffer_eol_style 386 * argument. Returns a newly allocated nul-terminated string; the caller must 387 * free the returned value. The EOL is not included in the returned string. 388 * 389 * @param buffer the evbuffer to read from 390 * @param n_read_out if non-NULL, points to a size_t that is set to the 391 * number of characters in the returned string. This is useful for 392 * strings that can contain NUL characters. 393 * @param eol_style the style of line-ending to use. 394 * @return pointer to a single line, or NULL if an error occurred 395 */ 396char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out, 397 enum evbuffer_eol_style eol_style); 398 399/** 400 Move all data from one evbuffer into another evbuffer. 401 402 This is a destructive add. The data from one buffer moves into 403 the other buffer. However, no unnecessary memory copies occur. 404 405 @param outbuf the output buffer 406 @param inbuf the input buffer 407 @return 0 if successful, or -1 if an error occurred 408 409 @see evbuffer_remove_buffer() 410 */ 411int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf); 412 413/** 414 A cleanup function for a piece of memory added to an evbuffer by 415 reference. 416 417 @see evbuffer_add_reference() 418 */ 419typedef void (*evbuffer_ref_cleanup_cb)(const void *data, 420 size_t datalen, void *extra); 421 422/** 423 Reference memory into an evbuffer without copying. 424 425 The memory needs to remain valid until all the added data has been 426 read. This function keeps just a reference to the memory without 427 actually incurring the overhead of a copy. 428 429 @param outbuf the output buffer 430 @param data the memory to reference 431 @param datlen how memory to reference 432 @param cleanupfn callback to be invoked when the memory is no longer 433 referenced by this evbuffer. 434 @param cleanupfn_arg optional argument to the cleanup callback 435 @return 0 if successful, or -1 if an error occurred 436 */ 437int evbuffer_add_reference(struct evbuffer *outbuf, 438 const void *data, size_t datlen, 439 evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg); 440 441/** 442 Copy data from a file into the evbuffer for writing to a socket. 443 444 This function avoids unnecessary data copies between userland and 445 kernel. If sendfile is available and the EVBUFFER_FLAG_DRAINS_TO_FD 446 flag is set, it uses those functions. Otherwise, it tries to use 447 mmap (or CreateFileMapping on Windows). 448 449 The function owns the resulting file descriptor and will close it 450 when finished transferring data. 451 452 The results of using evbuffer_remove() or evbuffer_pullup() on 453 evbuffers whose data was added using this function are undefined. 454 455 @param outbuf the output buffer 456 @param fd the file descriptor 457 @param offset the offset from which to read data 458 @param length how much data to read 459 @return 0 if successful, or -1 if an error occurred 460*/ 461 462int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset, 463 ev_off_t length); 464 465/** 466 Append a formatted string to the end of an evbuffer. 467 468 The string is formated as printf. 469 470 @param buf the evbuffer that will be appended to 471 @param fmt a format string 472 @param ... arguments that will be passed to printf(3) 473 @return The number of bytes added if successful, or -1 if an error occurred. 474 475 @see evutil_printf(), evbuffer_add_vprintf() 476 */ 477int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...) 478#ifdef __GNUC__ 479 __attribute__((format(printf, 2, 3))) 480#endif 481; 482 483/** 484 Append a va_list formatted string to the end of an evbuffer. 485 486 @param buf the evbuffer that will be appended to 487 @param fmt a format string 488 @param ap a varargs va_list argument array that will be passed to vprintf(3) 489 @return The number of bytes added if successful, or -1 if an error occurred. 490 */ 491int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap); 492 493 494/** 495 Remove a specified number of bytes data from the beginning of an evbuffer. 496 497 @param buf the evbuffer to be drained 498 @param len the number of bytes to drain from the beginning of the buffer 499 @return 0 on success, -1 on failure. 500 */ 501int evbuffer_drain(struct evbuffer *buf, size_t len); 502 503 504/** 505 Write the contents of an evbuffer to a file descriptor. 506 507 The evbuffer will be drained after the bytes have been successfully written. 508 509 @param buffer the evbuffer to be written and drained 510 @param fd the file descriptor to be written to 511 @return the number of bytes written, or -1 if an error occurred 512 @see evbuffer_read() 513 */ 514int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd); 515 516/** 517 Write some of the contents of an evbuffer to a file descriptor. 518 519 The evbuffer will be drained after the bytes have been successfully written. 520 521 @param buffer the evbuffer to be written and drained 522 @param fd the file descriptor to be written to 523 @param howmuch the largest allowable number of bytes to write, or -1 524 to write as many bytes as we can. 525 @return the number of bytes written, or -1 if an error occurred 526 @see evbuffer_read() 527 */ 528int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd, 529 ev_ssize_t howmuch); 530 531/** 532 Read from a file descriptor and store the result in an evbuffer. 533 534 @param buffer the evbuffer to store the result 535 @param fd the file descriptor to read from 536 @param howmuch the number of bytes to be read 537 @return the number of bytes read, or -1 if an error occurred 538 @see evbuffer_write() 539 */ 540int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch); 541 542/** 543 Search for a string within an evbuffer. 544 545 @param buffer the evbuffer to be searched 546 @param what the string to be searched for 547 @param len the length of the search string 548 @param start NULL or a pointer to a valid struct evbuffer_ptr. 549 @return a struct evbuffer_ptr whose 'pos' field has the offset of the 550 first occurrence of the string in the buffer after 'start'. The 'pos' 551 field of the result is -1 if the string was not found. 552 */ 553struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start); 554 555/** 556 Search for a string within part of an evbuffer. 557 558 @param buffer the evbuffer to be searched 559 @param what the string to be searched for 560 @param len the length of the search string 561 @param start NULL or a pointer to a valid struct evbuffer_ptr that 562 indicates where we should start searching. 563 @param end NULL or a pointer to a valid struct evbuffer_ptr that 564 indicates where we should stop searching. 565 @return a struct evbuffer_ptr whose 'pos' field has the offset of the 566 first occurrence of the string in the buffer after 'start'. The 'pos' 567 field of the result is -1 if the string was not found. 568 */ 569struct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start, const struct evbuffer_ptr *end); 570 571/** 572 Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set() 573 574 @see evbuffer_ptr_set() */ 575enum evbuffer_ptr_how { 576 /** Sets the pointer to the position; can be called on with an 577 uninitialized evbuffer_ptr. */ 578 EVBUFFER_PTR_SET, 579 /** Advances the pointer by adding to the current position. */ 580 EVBUFFER_PTR_ADD 581}; 582 583/** 584 Sets the search pointer in the buffer to position. 585 586 If evbuffer_ptr is not initialized. This function can only be called 587 with EVBUFFER_PTR_SET. 588 589 @param buffer the evbuffer to be search 590 @param ptr a pointer to a struct evbuffer_ptr 591 @param position the position at which to start the next search 592 @param how determines how the pointer should be manipulated. 593 @returns 0 on success or -1 otherwise 594*/ 595int 596evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr, 597 size_t position, enum evbuffer_ptr_how how); 598 599/** 600 Search for an end-of-line string within an evbuffer. 601 602 @param buffer the evbuffer to be searched 603 @param start NULL or a pointer to a valid struct evbuffer_ptr to start 604 searching at. 605 @param eol_len_out If non-NULL, the pointed-to value will be set to 606 the length of the end-of-line string. 607 @param eol_style The kind of EOL to look for; see evbuffer_readln() for 608 more information 609 @return a struct evbuffer_ptr whose 'pos' field has the offset of the 610 first occurrence EOL in the buffer after 'start'. The 'pos' 611 field of the result is -1 if the string was not found. 612 */ 613struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer, 614 struct evbuffer_ptr *start, size_t *eol_len_out, 615 enum evbuffer_eol_style eol_style); 616 617/** Function to peek at data inside an evbuffer without removing it or 618 copying it out. 619 620 Pointers to the data are returned by filling the 'vec_out' array 621 with pointers to one or more extents of data inside the buffer. 622 623 The total data in the extents that you get back may be more than 624 you requested (if there is more data last extent than you asked 625 for), or less (if you do not provide enough evbuffer_iovecs, or if 626 the buffer does not have as much data as you asked to see). 627 628 @param buffer the evbuffer to peek into, 629 @param len the number of bytes to try to peek. If len is negative, we 630 will try to fill as much of vec_out as we can. If len is negative 631 and vec_out is not provided, we return the number of evbuffer_iovecs 632 that would be needed to get all the data in the buffer. 633 @param start_at an evbuffer_ptr indicating the point at which we 634 should start looking for data. NULL means, "At the start of the 635 buffer." 636 @param vec_out an array of evbuffer_iovec 637 @param n_vec the length of vec_out. If 0, we only count how many 638 extents would be necessary to point to the requested amount of 639 data. 640 @return The number of extents needed. This may be less than n_vec 641 if we didn't need all the evbuffer_iovecs we were given, or more 642 than n_vec if we would need more to return all the data that was 643 requested. 644 */ 645int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len, 646 struct evbuffer_ptr *start_at, 647 struct evbuffer_iovec *vec_out, int n_vec); 648 649 650/** Structure passed to an evbuffer_cb_func evbuffer callback 651 652 @see evbuffer_cb_func, evbuffer_add_cb() 653 */ 654struct evbuffer_cb_info { 655 /** The number of bytes in this evbuffer when callbacks were last 656 * invoked. */ 657 size_t orig_size; 658 /** The number of bytes added since callbacks were last invoked. */ 659 size_t n_added; 660 /** The number of bytes removed since callbacks were last invoked. */ 661 size_t n_deleted; 662}; 663 664/** Type definition for a callback that is invoked whenever data is added or 665 removed from an evbuffer. 666 667 An evbuffer may have one or more callbacks set at a time. The order 668 in which they are executed is undefined. 669 670 A callback function may add more callbacks, or remove itself from the 671 list of callbacks, or add or remove data from the buffer. It may not 672 remove another callback from the list. 673 674 If a callback adds or removes data from the buffer or from another 675 buffer, this can cause a recursive invocation of your callback or 676 other callbacks. If you ask for an infinite loop, you might just get 677 one: watch out! 678 679 @param buffer the buffer whose size has changed 680 @param info a structure describing how the buffer changed. 681 @param arg a pointer to user data 682*/ 683typedef void (*evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg); 684 685struct evbuffer_cb_entry; 686/** Add a new callback to an evbuffer. 687 688 Subsequent calls to evbuffer_add_cb() add new callbacks. To remove this 689 callback, call evbuffer_remove_cb or evbuffer_remove_cb_entry. 690 691 @param buffer the evbuffer to be monitored 692 @param cb the callback function to invoke when the evbuffer is modified, 693 or NULL to remove all callbacks. 694 @param cbarg an argument to be provided to the callback function 695 @return a handle to the callback on success, or NULL on failure. 696 */ 697struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg); 698 699/** Remove a callback from an evbuffer, given a handle returned from 700 evbuffer_add_cb. 701 702 Calling this function invalidates the handle. 703 704 @return 0 if a callback was removed, or -1 if no matching callback was 705 found. 706 */ 707int evbuffer_remove_cb_entry(struct evbuffer *buffer, 708 struct evbuffer_cb_entry *ent); 709 710/** Remove a callback from an evbuffer, given the function and argument 711 used to add it. 712 713 @return 0 if a callback was removed, or -1 if no matching callback was 714 found. 715 */ 716int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg); 717 718/** If this flag is not set, then a callback is temporarily disabled, and 719 * should not be invoked. 720 * 721 * @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags() 722 */ 723#define EVBUFFER_CB_ENABLED 1 724 725/** Change the flags that are set for a callback on a buffer by adding more. 726 727 @param buffer the evbuffer that the callback is watching. 728 @param cb the callback whose status we want to change. 729 @param flags EVBUFFER_CB_ENABLED to re-enable the callback. 730 @return 0 on success, -1 on failure. 731 */ 732int evbuffer_cb_set_flags(struct evbuffer *buffer, 733 struct evbuffer_cb_entry *cb, ev_uint32_t flags); 734 735/** Change the flags that are set for a callback on a buffer by removing some 736 737 @param buffer the evbuffer that the callback is watching. 738 @param cb the callback whose status we want to change. 739 @param flags EVBUFFER_CB_ENABLED to disable the callback. 740 @return 0 on success, -1 on failure. 741 */ 742int evbuffer_cb_clear_flags(struct evbuffer *buffer, 743 struct evbuffer_cb_entry *cb, ev_uint32_t flags); 744 745#if 0 746/** Postpone calling a given callback until unsuspend is called later. 747 748 This is different from disabling the callback, since the callback will get 749 invoked later if the buffer size changes between now and when we unsuspend 750 it. 751 752 @param the buffer that the callback is watching. 753 @param cb the callback we want to suspend. 754 */ 755void evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb); 756/** Stop postponing a callback that we postponed with evbuffer_cb_suspend. 757 758 If data was added to or removed from the buffer while the callback was 759 suspended, the callback will get called once now. 760 761 @param the buffer that the callback is watching. 762 @param cb the callback we want to stop suspending. 763 */ 764void evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb); 765#endif 766 767/** 768 Makes the data at the begging of an evbuffer contiguous. 769 770 @param buf the evbuffer to make contiguous 771 @param size the number of bytes to make contiguous, or -1 to make the 772 entire buffer contiguous. 773 @return a pointer to the contiguous memory array 774*/ 775 776unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size); 777 778/** 779 Prepends data to the beginning of the evbuffer 780 781 @param buf the evbuffer to which to prepend data 782 @param data a pointer to the memory to prepend 783 @param size the number of bytes to prepend 784 @return 0 if successful, or -1 otherwise 785*/ 786 787int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size); 788 789/** 790 Prepends all data from the src evbuffer to the beginning of the dst 791 evbuffer. 792 793 @param dst the evbuffer to which to prepend data 794 @param src the evbuffer to prepend; it will be emptied as a result 795 @return 0 if successful, or -1 otherwise 796*/ 797int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src); 798 799/** 800 Prevent calls that modify an evbuffer from succeeding. A buffer may 801 frozen at the front, at the back, or at both the front and the back. 802 803 If the front of a buffer is frozen, operations that drain data from 804 the front of the buffer, or that prepend data to the buffer, will 805 fail until it is unfrozen. If the back a buffer is frozen, operations 806 that append data from the buffer will fail until it is unfrozen. 807 808 @param buf The buffer to freeze 809 @param at_front If true, we freeze the front of the buffer. If false, 810 we freeze the back. 811 @return 0 on success, -1 on failure. 812*/ 813int evbuffer_freeze(struct evbuffer *buf, int at_front); 814/** 815 Re-enable calls that modify an evbuffer. 816 817 @param buf The buffer to un-freeze 818 @param at_front If true, we unfreeze the front of the buffer. If false, 819 we unfreeze the back. 820 @return 0 on success, -1 on failure. 821 */ 822int evbuffer_unfreeze(struct evbuffer *buf, int at_front); 823 824struct event_base; 825/** 826 Force all the callbacks on an evbuffer to be run, not immediately after 827 the evbuffer is altered, but instead from inside the event loop. 828 829 This can be used to serialize all the callbacks to a single thread 830 of execution. 831 */ 832int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base); 833 834#ifdef __cplusplus 835} 836#endif 837 838#endif /* _EVENT2_BUFFER_H_ */ 839