root/opal/mca/event/libevent2022/libevent/include/event2/buffer.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   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
  76 extern "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 */
  95 struct 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  */
 109 struct 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
 129 struct 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  */
 143 struct evbuffer *evbuffer_new(void);
 144 /**
 145   Deallocate storage for an evbuffer.
 146 
 147   @param buf pointer to the evbuffer to be freed
 148  */
 149 void 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  */
 163 int 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 */
 169 void 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 */
 175 void 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  */
 202 int 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  */
 210 int 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 */
 218 size_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 */
 232 size_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 */
 244 int 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 */
 279 int
 280 evbuffer_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 */
 304 int 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  */
 315 int 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  */
 329 int 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  */
 342 ev_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  */
 357 int 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  */
 362 enum 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  */
 396 char *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  */
 411 int 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  */
 419 typedef 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  */
 437 int 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 
 462 int 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  */
 477 int 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  */
 491 int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap)
 492 #ifdef __GNUC__
 493         __attribute__((format(printf, 2, 0)))
 494 #endif
 495 ;
 496 
 497 
 498 /**
 499   Remove a specified number of bytes data from the beginning of an evbuffer.
 500 
 501   @param buf the evbuffer to be drained
 502   @param len the number of bytes to drain from the beginning of the buffer
 503   @return 0 on success, -1 on failure.
 504  */
 505 int evbuffer_drain(struct evbuffer *buf, size_t len);
 506 
 507 
 508 /**
 509   Write the contents of an evbuffer to a file descriptor.
 510 
 511   The evbuffer will be drained after the bytes have been successfully written.
 512 
 513   @param buffer the evbuffer to be written and drained
 514   @param fd the file descriptor to be written to
 515   @return the number of bytes written, or -1 if an error occurred
 516   @see evbuffer_read()
 517  */
 518 int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd);
 519 
 520 /**
 521   Write some of the contents of an evbuffer to a file descriptor.
 522 
 523   The evbuffer will be drained after the bytes have been successfully written.
 524 
 525   @param buffer the evbuffer to be written and drained
 526   @param fd the file descriptor to be written to
 527   @param howmuch the largest allowable number of bytes to write, or -1
 528         to write as many bytes as we can.
 529   @return the number of bytes written, or -1 if an error occurred
 530   @see evbuffer_read()
 531  */
 532 int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,
 533                                                   ev_ssize_t howmuch);
 534 
 535 /**
 536   Read from a file descriptor and store the result in an evbuffer.
 537 
 538   @param buffer the evbuffer to store the result
 539   @param fd the file descriptor to read from
 540   @param howmuch the number of bytes to be read
 541   @return the number of bytes read, or -1 if an error occurred
 542   @see evbuffer_write()
 543  */
 544 int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch);
 545 
 546 /**
 547    Search for a string within an evbuffer.
 548 
 549    @param buffer the evbuffer to be searched
 550    @param what the string to be searched for
 551    @param len the length of the search string
 552    @param start NULL or a pointer to a valid struct evbuffer_ptr.
 553    @return a struct evbuffer_ptr whose 'pos' field has the offset of the
 554      first occurrence of the string in the buffer after 'start'.  The 'pos'
 555      field of the result is -1 if the string was not found.
 556  */
 557 struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start);
 558 
 559 /**
 560    Search for a string within part of an evbuffer.
 561 
 562    @param buffer the evbuffer to be searched
 563    @param what the string to be searched for
 564    @param len the length of the search string
 565    @param start NULL or a pointer to a valid struct evbuffer_ptr that
 566      indicates where we should start searching.
 567    @param end NULL or a pointer to a valid struct evbuffer_ptr that
 568      indicates where we should stop searching.
 569    @return a struct evbuffer_ptr whose 'pos' field has the offset of the
 570      first occurrence of the string in the buffer after 'start'.  The 'pos'
 571      field of the result is -1 if the string was not found.
 572  */
 573 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);
 574 
 575 /**
 576    Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set()
 577 
 578    @see evbuffer_ptr_set() */
 579 enum evbuffer_ptr_how {
 580         /** Sets the pointer to the position; can be called on with an
 581             uninitialized evbuffer_ptr. */
 582         EVBUFFER_PTR_SET,
 583         /** Advances the pointer by adding to the current position. */
 584         EVBUFFER_PTR_ADD
 585 };
 586 
 587 /**
 588    Sets the search pointer in the buffer to position.
 589 
 590    If evbuffer_ptr is not initialized.  This function can only be called
 591    with EVBUFFER_PTR_SET.
 592 
 593    @param buffer the evbuffer to be search
 594    @param ptr a pointer to a struct evbuffer_ptr
 595    @param position the position at which to start the next search
 596    @param how determines how the pointer should be manipulated.
 597    @returns 0 on success or -1 otherwise
 598 */
 599 int
 600 evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr,
 601     size_t position, enum evbuffer_ptr_how how);
 602 
 603 /**
 604    Search for an end-of-line string within an evbuffer.
 605 
 606    @param buffer the evbuffer to be searched
 607    @param start NULL or a pointer to a valid struct evbuffer_ptr to start
 608       searching at.
 609    @param eol_len_out If non-NULL, the pointed-to value will be set to
 610       the length of the end-of-line string.
 611    @param eol_style The kind of EOL to look for; see evbuffer_readln() for
 612       more information
 613    @return a struct evbuffer_ptr whose 'pos' field has the offset of the
 614      first occurrence EOL in the buffer after 'start'.  The 'pos'
 615      field of the result is -1 if the string was not found.
 616  */
 617 struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
 618     struct evbuffer_ptr *start, size_t *eol_len_out,
 619     enum evbuffer_eol_style eol_style);
 620 
 621 /** Function to peek at data inside an evbuffer without removing it or
 622     copying it out.
 623 
 624     Pointers to the data are returned by filling the 'vec_out' array
 625     with pointers to one or more extents of data inside the buffer.
 626 
 627     The total data in the extents that you get back may be more than
 628     you requested (if there is more data last extent than you asked
 629     for), or less (if you do not provide enough evbuffer_iovecs, or if
 630     the buffer does not have as much data as you asked to see).
 631 
 632     @param buffer the evbuffer to peek into,
 633     @param len the number of bytes to try to peek.  If len is negative, we
 634        will try to fill as much of vec_out as we can.  If len is negative
 635        and vec_out is not provided, we return the number of evbuffer_iovecs
 636        that would be needed to get all the data in the buffer.
 637     @param start_at an evbuffer_ptr indicating the point at which we
 638        should start looking for data.  NULL means, "At the start of the
 639        buffer."
 640     @param vec_out an array of evbuffer_iovec
 641     @param n_vec the length of vec_out.  If 0, we only count how many
 642        extents would be necessary to point to the requested amount of
 643        data.
 644     @return The number of extents needed.  This may be less than n_vec
 645        if we didn't need all the evbuffer_iovecs we were given, or more
 646        than n_vec if we would need more to return all the data that was
 647        requested.
 648  */
 649 int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,
 650     struct evbuffer_ptr *start_at,
 651     struct evbuffer_iovec *vec_out, int n_vec);
 652 
 653 
 654 /** Structure passed to an evbuffer_cb_func evbuffer callback
 655 
 656     @see evbuffer_cb_func, evbuffer_add_cb()
 657  */
 658 struct evbuffer_cb_info {
 659         /** The number of bytes in this evbuffer when callbacks were last
 660          * invoked. */
 661         size_t orig_size;
 662         /** The number of bytes added since callbacks were last invoked. */
 663         size_t n_added;
 664         /** The number of bytes removed since callbacks were last invoked. */
 665         size_t n_deleted;
 666 };
 667 
 668 /** Type definition for a callback that is invoked whenever data is added or
 669     removed from an evbuffer.
 670 
 671     An evbuffer may have one or more callbacks set at a time.  The order
 672     in which they are executed is undefined.
 673 
 674     A callback function may add more callbacks, or remove itself from the
 675     list of callbacks, or add or remove data from the buffer.  It may not
 676     remove another callback from the list.
 677 
 678     If a callback adds or removes data from the buffer or from another
 679     buffer, this can cause a recursive invocation of your callback or
 680     other callbacks.  If you ask for an infinite loop, you might just get
 681     one: watch out!
 682 
 683     @param buffer the buffer whose size has changed
 684     @param info a structure describing how the buffer changed.
 685     @param arg a pointer to user data
 686 */
 687 typedef void (*evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg);
 688 
 689 struct evbuffer_cb_entry;
 690 /** Add a new callback to an evbuffer.
 691 
 692   Subsequent calls to evbuffer_add_cb() add new callbacks.  To remove this
 693   callback, call evbuffer_remove_cb or evbuffer_remove_cb_entry.
 694 
 695   @param buffer the evbuffer to be monitored
 696   @param cb the callback function to invoke when the evbuffer is modified,
 697         or NULL to remove all callbacks.
 698   @param cbarg an argument to be provided to the callback function
 699   @return a handle to the callback on success, or NULL on failure.
 700  */
 701 struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
 702 
 703 /** Remove a callback from an evbuffer, given a handle returned from
 704     evbuffer_add_cb.
 705 
 706     Calling this function invalidates the handle.
 707 
 708     @return 0 if a callback was removed, or -1 if no matching callback was
 709     found.
 710  */
 711 int evbuffer_remove_cb_entry(struct evbuffer *buffer,
 712                              struct evbuffer_cb_entry *ent);
 713 
 714 /** Remove a callback from an evbuffer, given the function and argument
 715     used to add it.
 716 
 717     @return 0 if a callback was removed, or -1 if no matching callback was
 718     found.
 719  */
 720 int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
 721 
 722 /** If this flag is not set, then a callback is temporarily disabled, and
 723  * should not be invoked.
 724  *
 725  * @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags()
 726  */
 727 #define EVBUFFER_CB_ENABLED 1
 728 
 729 /** Change the flags that are set for a callback on a buffer by adding more.
 730 
 731     @param buffer the evbuffer that the callback is watching.
 732     @param cb the callback whose status we want to change.
 733     @param flags EVBUFFER_CB_ENABLED to re-enable the callback.
 734     @return 0 on success, -1 on failure.
 735  */
 736 int evbuffer_cb_set_flags(struct evbuffer *buffer,
 737                           struct evbuffer_cb_entry *cb, ev_uint32_t flags);
 738 
 739 /** Change the flags that are set for a callback on a buffer by removing some
 740 
 741     @param buffer the evbuffer that the callback is watching.
 742     @param cb the callback whose status we want to change.
 743     @param flags EVBUFFER_CB_ENABLED to disable the callback.
 744     @return 0 on success, -1 on failure.
 745  */
 746 int evbuffer_cb_clear_flags(struct evbuffer *buffer,
 747                           struct evbuffer_cb_entry *cb, ev_uint32_t flags);
 748 
 749 #if 0
 750 /** Postpone calling a given callback until unsuspend is called later.
 751 
 752     This is different from disabling the callback, since the callback will get
 753         invoked later if the buffer size changes between now and when we unsuspend
 754         it.
 755 
 756         @param the buffer that the callback is watching.
 757         @param cb the callback we want to suspend.
 758  */
 759 void evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
 760 /** Stop postponing a callback that we postponed with evbuffer_cb_suspend.
 761 
 762         If data was added to or removed from the buffer while the callback was
 763         suspended, the callback will get called once now.
 764 
 765         @param the buffer that the callback is watching.
 766         @param cb the callback we want to stop suspending.
 767  */
 768 void evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
 769 #endif
 770 
 771 /**
 772   Makes the data at the beginning of an evbuffer contiguous.
 773 
 774   @param buf the evbuffer to make contiguous
 775   @param size the number of bytes to make contiguous, or -1 to make the
 776         entire buffer contiguous.
 777   @return a pointer to the contiguous memory array
 778 */
 779 
 780 unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size);
 781 
 782 /**
 783   Prepends data to the beginning of the evbuffer
 784 
 785   @param buf the evbuffer to which to prepend data
 786   @param data a pointer to the memory to prepend
 787   @param size the number of bytes to prepend
 788   @return 0 if successful, or -1 otherwise
 789 */
 790 
 791 int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size);
 792 
 793 /**
 794   Prepends all data from the src evbuffer to the beginning of the dst
 795   evbuffer.
 796 
 797   @param dst the evbuffer to which to prepend data
 798   @param src the evbuffer to prepend; it will be emptied as a result
 799   @return 0 if successful, or -1 otherwise
 800 */
 801 int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src);
 802 
 803 /**
 804    Prevent calls that modify an evbuffer from succeeding. A buffer may
 805    frozen at the front, at the back, or at both the front and the back.
 806 
 807    If the front of a buffer is frozen, operations that drain data from
 808    the front of the buffer, or that prepend data to the buffer, will
 809    fail until it is unfrozen.   If the back a buffer is frozen, operations
 810    that append data from the buffer will fail until it is unfrozen.
 811 
 812    @param buf The buffer to freeze
 813    @param at_front If true, we freeze the front of the buffer.  If false,
 814       we freeze the back.
 815    @return 0 on success, -1 on failure.
 816 */
 817 int evbuffer_freeze(struct evbuffer *buf, int at_front);
 818 /**
 819    Re-enable calls that modify an evbuffer.
 820 
 821    @param buf The buffer to un-freeze
 822    @param at_front If true, we unfreeze the front of the buffer.  If false,
 823       we unfreeze the back.
 824    @return 0 on success, -1 on failure.
 825  */
 826 int evbuffer_unfreeze(struct evbuffer *buf, int at_front);
 827 
 828 struct event_base;
 829 /**
 830    Force all the callbacks on an evbuffer to be run, not immediately after
 831    the evbuffer is altered, but instead from inside the event loop.
 832 
 833    This can be used to serialize all the callbacks to a single thread
 834    of execution.
 835  */
 836 int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base);
 837 
 838 #ifdef __cplusplus
 839 }
 840 #endif
 841 
 842 #endif /* _EVENT2_BUFFER_H_ */

/* [<][>][^][v][top][bottom][index][help] */