include/event2/buffer_compat.h

0001 /*
0002  * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
0003  *
0004  * Redistribution and use in source and binary forms, with or without
0005  * modification, are permitted provided that the following conditions
0006  * are met:
0007  * 1. Redistributions of source code must retain the above copyright
0008  *    notice, this list of conditions and the following disclaimer.
0009  * 2. Redistributions in binary form must reproduce the above copyright
0010  *    notice, this list of conditions and the following disclaimer in the
0011  *    documentation and/or other materials provided with the distribution.
0012  * 3. The name of the author may not be used to endorse or promote products
0013  *    derived from this software without specific prior written permission.
0014  *
0015  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
0016  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
0017  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
0018  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
0019  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
0020  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0021  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0022  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0023  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
0024  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0025  */
0026
0027 #ifndef EVENT2_BUFFER_COMPAT_H_INCLUDED_
0028 #define EVENT2_BUFFER_COMPAT_H_INCLUDED_
0029
0030 #include <event2/visibility.h>
0031
0032 /** @file event2/buffer_compat.h
0033
0034     Obsolete and deprecated versions of the functions in buffer.h: provided
0035     only for backward compatibility.
0036  */
0037
0038
0039 /**
0040    Obsolete alias for evbuffer_readln(buffer, NULL, EVBUFFER_EOL_ANY).
0041
0042    @deprecated This function is deprecated because its behavior is not correct
0043       for almost any protocol, and also because it's wholly subsumed by
0044       evbuffer_readln().
0045
0046    @param buffer the evbuffer to read from
0047    @return pointer to a single line, or NULL if an error occurred
0048
0049 */
0050 EVENT2_EXPORT_SYMBOL
0051 char *evbuffer_readline(struct evbuffer *buffer);
0052
0053 /** Type definition for a callback that is invoked whenever data is added or
0054     removed from an evbuffer.
0055
0056     An evbuffer may have one or more callbacks set at a time.  The order
0057     in which they are executed is undefined.
0058
0059     A callback function may add more callbacks, or remove itself from the
0060     list of callbacks, or add or remove data from the buffer.  It may not
0061     remove another callback from the list.
0062
0063     If a callback adds or removes data from the buffer or from another
0064     buffer, this can cause a recursive invocation of your callback or
0065     other callbacks.  If you ask for an infinite loop, you might just get
0066     one: watch out!
0067
0068     @param buffer the buffer whose size has changed
0069     @param old_len the previous length of the buffer
0070     @param new_len the current length of the buffer
0071     @param arg a pointer to user data
0072 */
0073 typedef void (*evbuffer_cb)(struct evbuffer *buffer, size_t old_len, size_t new_len, void *arg);
0074
0075 /**
0076   Replace all callbacks on an evbuffer with a single new callback, or
0077   remove them.
0078
0079   Subsequent calls to evbuffer_setcb() replace callbacks set by previous
0080   calls.  Setting the callback to NULL removes any previously set callback.
0081
0082   @deprecated This function is deprecated because it clears all previous
0083      callbacks set on the evbuffer, which can cause confusing behavior if
0084      multiple parts of the code all want to add their own callbacks on a
0085      buffer.  Instead, use evbuffer_add(), evbuffer_del(), and
0086      evbuffer_setflags() to manage your own evbuffer callbacks without
0087      interfering with callbacks set by others.
0088
0089   @param buffer the evbuffer to be monitored
0090   @param cb the callback function to invoke when the evbuffer is modified,
0091      or NULL to remove all callbacks.
0092   @param cbarg an argument to be provided to the callback function
0093   @return 0 if successful, or -1 on error
0094  */
0095 EVENT2_EXPORT_SYMBOL
0096 int evbuffer_setcb(struct evbuffer *buffer, evbuffer_cb cb, void *cbarg);
0097
0098
0099 /**
0100   Find a string within an evbuffer.
0101
0102   @param buffer the evbuffer to be searched
0103   @param what the string to be searched for
0104   @param len the length of the search string
0105   @return a pointer to the beginning of the search string, or NULL if the search failed.
0106  */
0107 EVENT2_EXPORT_SYMBOL
0108 unsigned char *evbuffer_find(struct evbuffer *buffer, const unsigned char *what, size_t len);
0109
0110 /** deprecated in favor of calling the functions directly */
0111 #define EVBUFFER_LENGTH(x)  evbuffer_get_length(x)
0112 /** deprecated in favor of calling the functions directly */
0113 #define EVBUFFER_DATA(x)    evbuffer_pullup((x), -1)
0114
0115 #endif
0116