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