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