s3-lib: add cbuf, a talloced character buffer

Signed-off-by: Michael Adam <obnox@samba.org>

1 files changed, 235 insertions, 0 deletions

diff --git a/source3/lib/cbuf.h b/source3/lib/cbuf.h
new file mode 100644
index 0000000000..ffb52d7b9a
--- /dev/null
+++ b/source3/lib/cbuf.h
@@ -0,0 +1,235 @@
+/*
+ * Samba Unix/Linux SMB client library
+ * Copyright (C) Gregor Beck 2010
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * @file   cbuf.h
+ * @author Gregor Beck <gb@sernet.de>
+ * @date   Aug 2010
+ *
+ * @brief  A talloced character buffer.
+ *
+ * A cbuf carries a write position and keeps track of its size.
+ */
+
+#ifndef __CBUF_H
+#define __CBUF_H
+
+#include <stddef.h>
+#include <stdbool.h>
+#include <stdint.h>
+
+
+struct cbuf;
+typedef struct cbuf cbuf;
+
+/**
+ * Create a new character buffer.
+ *
+ * @param talloc_ctx the talloc parent
+ *
+ * @return a new cbuf object, NULL on error
+ */
+cbuf* cbuf_new(const void* talloc_ctx);
+
+/**
+ * Create a copy of a character buffer.
+ *
+ * @param b the cbuf to copy
+ * @return a new cbuf object, NULL on error
+ */
+cbuf* cbuf_copy(const cbuf* b);
+
+/**
+ * Delete a character buffer.
+ * This invalidates b and free's the memory allocated.
+ * @warning don't talloc_free b directly, however freeing
+ *          the parent works as expected
+ * @param b the cbuf to delete
+ */
+void  cbuf_delete(cbuf* b);
+
+/**
+ * Reset the buffer to initial state.
+ * Set the write positon to the start of buffer, effectivly
+ * clearing its contents. Doesn't free memory.
+ *
+ * @param b the buffer to clear
+ *
+ * @return b
+ */
+cbuf* cbuf_clear(cbuf* b);
+
+/**
+ * Swap the contents of two buffers in O(1).
+ *
+ * @param b1 a character buffer
+ * @param b2 another character buffer
+ */
+void cbuf_swap(cbuf* b1, cbuf* b2);
+
+/**
+ * Swap the contents of a buffer with a talloced string.
+ *
+ * @param b a character buffer
+ * @param ptr a pointer to a talloced string
+ * @param len size of string, -1 means strlen(*ptr)
+ *
+ * @return b
+ */
+cbuf* cbuf_swapptr(cbuf* b, char** ptr, size_t len);
+
+/**
+ * Let a character buffer takeover the contents of another.
+ * This is equivalent to @code
+ *   cbuf_swap(b1, b2);
+ *   cbuf_delete(b2);
+ * @endcode
+ * @param b1 the destination
+ * @param b2 the victim
+ *
+ * @return b1
+ */
+cbuf* cbuf_takeover(cbuf* b1, cbuf* b2);
+
+/**
+ * Resize a character buffer.
+ * This may free allocated memory.
+ *
+ * @param b the character buffer.
+ * @param size the new size
+ *
+ * @return b, NULL on error
+ */
+cbuf* cbuf_resize(cbuf* b, size_t size);
+
+/**
+ * Reserve space in a character buffer.
+ * Assert there are at least len bytes following the current write position.
+ *
+ * @param b a character buffer
+ * @param len number of bytes to reserve.
+ *
+ * @return a pointer to the current write position, NULL on error
+ */
+char* cbuf_reserve(cbuf* b, size_t len);
+
+/**
+ * Put a character into the buffer.
+ *
+ * @param b a charcter buffer, may be NULL.
+ * @param c a character
+ * @return number of charcters written ((b==NULL) ? 0 : 1)
+ *
+ * @retval -1 on error
+ */
+int cbuf_putc(cbuf* b, char c);
+
+/**
+ * Put a string into the buffer.
+ *
+ * @param b a character buffer, may be NULL
+ * @param str a string
+ * @param len number of bytes to write, -1 means strlen(str)
+ *
+ * @return number of characters written, -1 on error
+ */
+int cbuf_puts(cbuf* b, const char* str, size_t len);
+
+/* /\** */
+/*  * Put a string into the buffer, changing case. */
+/*  * */
+/*  * @param b a character buffer, may be NULL */
+/*  * @param str a string */
+/*  * @param len number of bytes to write, -1 means strlen(str) */
+/*  * @param c   a character specifying case: */
+/*  *        @li 'U' upper case */
+/*  *        @li 'L' lower case */
+/*  *        @li 'T' title case */
+/*  *        @li 'P' preserve case */
+/*  * @return number of characters written, -1 on error */
+/*  *\/ */
+/* int cbuf_puts_case(cbuf* b, const char* str, size_t len, char c); */
+
+
+
+/**
+ * Put a uint32 into the buffer.
+ * Write in little endian order.
+ *
+ * @param b a character buffer, may be NULL
+ * @param u an uint32
+ *
+ * @return number of characters written, -1 on error
+ */
+int cbuf_putdw(cbuf* b, uint32_t u);
+
+/**
+ * Print formated to a character buffer.
+ *
+ * @param b a charcter buffer
+ * @param fmt a printf format string
+ *
+ * @return number of characters written, negative on error
+ */
+int cbuf_printf(cbuf* b, const char* fmt, ...);
+
+
+/**
+ * Get the current write position.
+ *
+ * @param b a character buffer.
+ *
+ * @return index of the next charcter to write.
+ */
+size_t cbuf_getpos(const cbuf* b);
+
+/**
+ * Set the current write position of a buffer.
+ * Invalidates the buffer contents from on the new position.
+ *
+ * @param b a charcter buffer
+ * @param pos a position obtained by cbuf_getpos
+ */
+void cbuf_setpos(cbuf* b, size_t pos);
+
+/**
+ * Get the buffer contents
+ * starting at idx.
+ * @pre @code idx <= cbuf_getpos(b) @endcode
+ * @param b a character buffer
+ * @param idx a position obtained by cbuf_getpos
+ *
+ * @return a NUL terminated string
+ */
+char* cbuf_gets(cbuf* b, size_t idx);
+
+/**
+ * Print quoted string to stream.
+ *
+ * @todo check for ssputc failure
+ * @see srprs_quoted_string
+ *
+ * @param[out] ost outstream
+ * @param[in]  s string
+ *
+ * @return numner of bytes written, -1 on error
+ */
+int cbuf_print_quoted_string(cbuf* ost, const char* s);
+
+
+#endif /*__CBUF_H*/