* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

/** @file event2/buffer.h

evbuffer_peek() if you don't require that the memory to be contiguous.

*/

#ifdef __cplusplus

extern "C" {

#endif

#include <event2/event-config.h>

#include <stdarg.h>

#include <sys/types.h>

#endif

#include <sys/uio.h>

#endif

#include <event2/util.h>

@see event2/event.h for more information

*/

struct evbuffer

{}

#endif

;

Used when repeatedly searching through a buffer. Calling any function

that modifies or re-packs the buffer contents may invalidate all

*/

struct evbuffer_ptr {

ev_ssize_t pos;

struct {

void *chain;

size_t pos_in_chain;

};

/** Describes a single extent of memory inside an evbuffer. Used for

@see evbuffer_reserve_space, evbuffer_commit_space, evbuffer_peek

*/

#define evbuffer_iovec iovec

/* Internal use -- defined only if we are using the native struct iovec */

#else

struct evbuffer_iovec {

/** The start of the extent of memory. */

@return a pointer to a newly allocated evbuffer struct, or NULL if an error

occurred

*/

struct evbuffer *evbuffer_new(void);

/**

Deallocate storage for an evbuffer.

@param buf pointer to the evbuffer to be freed

*/

void evbuffer_free(struct evbuffer *buf);

/**

@param lock A lock object, or NULL if we should allocate our own.

@return 0 on success, -1 on failure.

*/

int evbuffer_enable_locking(struct evbuffer *buf, void *lock);

/**

Acquire the lock on an evbuffer. Has no effect if locking was not enabled

with evbuffer_enable_locking.

*/

void evbuffer_lock(struct evbuffer *buf);

/**

Release the lock on an evbuffer. Has no effect if locking was not enabled

with evbuffer_enable_locking.

*/

void evbuffer_unlock(struct evbuffer *buf);

* @param flags One or more EVBUFFER_FLAG_* options

* @return 0 on success, -1 on failure.

*/

int evbuffer_set_flags(struct evbuffer *buf, ev_uint64_t flags);

/** Change the flags that are set for an evbuffer by removing some.

*

* @param flags One or more EVBUFFER_FLAG_* options

* @return 0 on success, -1 on failure.

*/

int evbuffer_clear_flags(struct evbuffer *buf, ev_uint64_t flags);

/**

@param buf pointer to the evbuffer

@return the number of bytes stored in the evbuffer

*/

size_t evbuffer_get_length(const struct evbuffer *buf);

/**

@return 0 if no data is available, otherwise the number of available bytes

in the first buffer chain.

*/

size_t evbuffer_get_contiguous_space(const struct evbuffer *buf);

/**

@param datlen the new minimum length requirement

@return 0 if successful, or -1 if an error occurred

*/

int evbuffer_expand(struct evbuffer *buf, size_t datlen);

/**

@return the number of provided extents, or -1 on error.

@see evbuffer_commit_space()

*/

int

evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,

struct evbuffer_iovec *vec, int n_vec);

@return 0 on success, -1 on error

@see evbuffer_reserve_space()

*/

int evbuffer_commit_space(struct evbuffer *buf,

struct evbuffer_iovec *vec, int n_vecs);

@param datlen the number of bytes to be copied from the data buffer

@return 0 on success, -1 on failure.

*/

int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);

@param datlen the maximum size of the destination buffer

@return the number of bytes read, or -1 if we can't drain the buffer.

*/

int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);

/**

@param datlen the maximum size of the destination buffer

@return the number of bytes read, or -1 if we can't drain the buffer.

*/

ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen);

/**

Read data from an evbuffer into another evbuffer, draining

the bytes from the source buffer. This function avoids copy

operations to the extent possible.

@param datlen the maximum numbers of bytes to transfer

@return the number of bytes read

*/

int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst,

size_t datlen);

/** An EOL is a CR followed by an LF. */

EVBUFFER_EOL_CRLF_STRICT,

/** An EOL is a LF. */

};

/**

* @param eol_style the style of line-ending to use.

* @return pointer to a single line, or NULL if an error occurred

*/

char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,

enum evbuffer_eol_style eol_style);

@see evbuffer_remove_buffer()

*/

int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf);

/**

A cleanup function for a piece of memory added to an evbuffer by

reference.

@param cleanupfn_arg optional argument to the cleanup callback

@return 0 if successful, or -1 if an error occurred

*/

int evbuffer_add_reference(struct evbuffer *outbuf,

const void *data, size_t datlen,

evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg);

The results of using evbuffer_remove() or evbuffer_pullup() on

evbuffers whose data was added using this function are undefined.

@param outbuf the output buffer

@param fd the file descriptor

@param offset the offset from which to read data

@return 0 if successful, or -1 if an error occurred

*/

int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset,

ev_off_t length);

/**

Append a formatted string to the end of an evbuffer.

The string is formated as printf.

@see evutil_printf(), evbuffer_add_vprintf()

*/

int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)

#ifdef __GNUC__

__attribute__((format(printf, 2, 3)))

@param ap a varargs va_list argument array that will be passed to vprintf(3)

@return The number of bytes added if successful, or -1 if an error occurred.

*/

int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap)

#ifdef __GNUC__

__attribute__((format(printf, 2, 0)))

@param len the number of bytes to drain from the beginning of the buffer

@return 0 on success, -1 on failure.

*/

int evbuffer_drain(struct evbuffer *buf, size_t len);

@return the number of bytes written, or -1 if an error occurred

@see evbuffer_read()

*/

int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd);

/**

@return the number of bytes written, or -1 if an error occurred

@see evbuffer_read()

*/

int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,

ev_ssize_t howmuch);

@return the number of bytes read, or -1 if an error occurred

@see evbuffer_write()

*/

int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch);

/**

first occurrence of the string in the buffer after 'start'. The 'pos'

field of the result is -1 if the string was not found.

*/

struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start);

/**

first occurrence of the string in the buffer after 'start'. The 'pos'

field of the result is -1 if the string was not found.

*/

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);

/**

/**

Sets the search pointer in the buffer to position.

with EVBUFFER_PTR_SET.

@param buffer the evbuffer to be search

@param ptr a pointer to a struct evbuffer_ptr

@param position the position at which to start the next search

@param how determines how the pointer should be manipulated.

@returns 0 on success or -1 otherwise

*/

int

evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr,

size_t position, enum evbuffer_ptr_how how);

first occurrence EOL in the buffer after 'start'. The 'pos'

field of the result is -1 if the string was not found.

*/

struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,

struct evbuffer_ptr *start, size_t *eol_len_out,

enum evbuffer_eol_style eol_style);

than n_vec if we would need more to return all the data that was

requested.

*/

int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,

struct evbuffer_ptr *start_at,

struct evbuffer_iovec *vec_out, int n_vec);

@param cbarg an argument to be provided to the callback function

@return a handle to the callback on success, or NULL on failure.

*/

struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);

/** Remove a callback from an evbuffer, given a handle returned from

@return 0 if a callback was removed, or -1 if no matching callback was

found.

*/

int evbuffer_remove_cb_entry(struct evbuffer *buffer,

struct evbuffer_cb_entry *ent);

@return 0 if a callback was removed, or -1 if no matching callback was

found.

*/

int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);

/** If this flag is not set, then a callback is temporarily disabled, and

@param flags EVBUFFER_CB_ENABLED to re-enable the callback.

@return 0 on success, -1 on failure.

*/

int evbuffer_cb_set_flags(struct evbuffer *buffer,

struct evbuffer_cb_entry *cb, ev_uint32_t flags);

@param flags EVBUFFER_CB_ENABLED to disable the callback.

@return 0 on success, -1 on failure.

*/

int evbuffer_cb_clear_flags(struct evbuffer *buffer,

struct evbuffer_cb_entry *cb, ev_uint32_t flags);

@param the buffer that the callback is watching.

@param cb the callback we want to suspend.

*/

void evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);

/** Stop postponing a callback that we postponed with evbuffer_cb_suspend.

@param the buffer that the callback is watching.

@param cb the callback we want to stop suspending.

*/

void evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);

#endif

@param buf the evbuffer to make contiguous

@param size the number of bytes to make contiguous, or -1 to make the

entire buffer contiguous.

*/

unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size);

/**

@return 0 if successful, or -1 otherwise

*/

int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size);

/**

@param src the evbuffer to prepend; it will be emptied as a result

@return 0 if successful, or -1 otherwise

*/

int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src);

/**

we freeze the back.

@return 0 on success, -1 on failure.

*/

int evbuffer_freeze(struct evbuffer *buf, int at_front);

/**

Re-enable calls that modify an evbuffer.

we unfreeze the back.

@return 0 on success, -1 on failure.

*/

int evbuffer_unfreeze(struct evbuffer *buf, int at_front);

struct event_base;

This can be used to serialize all the callbacks to a single thread

of execution.

*/

int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base);

#ifdef __cplusplus

}

#endif