Home | History | Annotate | Line # | Download | only in event2 
      1 /*	$NetBSD: buffer_compat.h,v 1.6 2024/08/18 20:47:22 christos Exp $	*/
      2 
      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 
     29 #ifndef EVENT2_BUFFER_COMPAT_H_INCLUDED_
     30 #define EVENT2_BUFFER_COMPAT_H_INCLUDED_
     31 
     32 #include <event2/visibility.h>
     33 
     34 /** @file event2/buffer_compat.h
     35 
     36 	Obsolete and deprecated versions of the functions in buffer.h: provided
     37 	only for backward compatibility.
     38  */
     39 
     40 
     41 /**
     42    Obsolete alias for evbuffer_readln(buffer, NULL, EVBUFFER_EOL_ANY).
     43 
     44    @deprecated This function is deprecated because its behavior is not correct
     45       for almost any protocol, and also because it's wholly subsumed by
     46       evbuffer_readln().
     47 
     48    @param buffer the evbuffer to read from
     49    @return pointer to a single line, or NULL if an error occurred
     50 
     51 */
     52 EVENT2_EXPORT_SYMBOL
     53 char *evbuffer_readline(struct evbuffer *buffer);
     54 
     55 /** Type definition for a callback that is invoked whenever data is added or
     56     removed from an evbuffer.
     57 
     58     An evbuffer may have one or more callbacks set at a time.  The order
     59     in which they are executed is undefined.
     60 
     61     A callback function may add more callbacks, or remove itself from the
     62     list of callbacks, or add or remove data from the buffer.  It may not
     63     remove another callback from the list.
     64 
     65     If a callback adds or removes data from the buffer or from another
     66     buffer, this can cause a recursive invocation of your callback or
     67     other callbacks.  If you ask for an infinite loop, you might just get
     68     one: watch out!
     69 
     70     @param buffer the buffer whose size has changed
     71     @param old_len the previous length of the buffer
     72     @param new_len the current length of the buffer
     73     @param arg a pointer to user data
     74 */
     75 typedef void (*evbuffer_cb)(struct evbuffer *buffer, size_t old_len, size_t new_len, void *arg);
     76 
     77 /**
     78   Replace all callbacks on an evbuffer with a single new callback, or
     79   remove them.
     80 
     81   Subsequent calls to evbuffer_setcb() replace callbacks set by previous
     82   calls.  Setting the callback to NULL removes any previously set callback.
     83 
     84   @deprecated This function is deprecated because it clears all previous
     85      callbacks set on the evbuffer, which can cause confusing behavior if
     86      multiple parts of the code all want to add their own callbacks on a
     87      buffer.  Instead, use evbuffer_add(), evbuffer_del(), and
     88      evbuffer_setflags() to manage your own evbuffer callbacks without
     89      interfering with callbacks set by others.
     90 
     91   @param buffer the evbuffer to be monitored
     92   @param cb the callback function to invoke when the evbuffer is modified,
     93 	 or NULL to remove all callbacks.
     94   @param cbarg an argument to be provided to the callback function
     95   @return 0 if successful, or -1 on error
     96  */
     97 EVENT2_EXPORT_SYMBOL
     98 int evbuffer_setcb(struct evbuffer *buffer, evbuffer_cb cb, void *cbarg);
     99 
    100 
    101 /**
    102   Find a string within an evbuffer.
    103 
    104   @param buffer the evbuffer to be searched
    105   @param what the string to be searched for
    106   @param len the length of the search string
    107   @return a pointer to the beginning of the search string, or NULL if the search failed.
    108  */
    109 EVENT2_EXPORT_SYMBOL
    110 unsigned char *evbuffer_find(struct evbuffer *buffer, const unsigned char *what, size_t len);
    111 
    112 /** deprecated in favor of calling the functions directly */
    113 #define EVBUFFER_LENGTH(x)	evbuffer_get_length(x)
    114 /** deprecated in favor of calling the functions directly */
    115 #define EVBUFFER_DATA(x)	evbuffer_pullup((x), -1)
    116 
    117 #endif
    118 
    119