source3/lib/cbuf.h

   1 /*
   2  * Samba Unix/Linux SMB client library
   3  * Copyright (C) Gregor Beck 2010
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 /**
  20  * @file   cbuf.h
  21  * @author Gregor Beck <gb@sernet.de>
  22  * @date   Aug 2010
  23  *
  24  * @brief  A talloced character buffer.
  25  *
  26  * A cbuf carries a write position and keeps track of its size.
  27  */
  28
  29 #ifndef __CBUF_H
  30 #define __CBUF_H
  31
  32 #include <stddef.h>
  33 #include <stdbool.h>
  34 #include <stdint.h>
  35
  36
  37 struct cbuf;
  38 typedef struct cbuf cbuf;
  39
  40 /**
  41  * Create a new character buffer.
  42  *
  43  * @param talloc_ctx the talloc parent
  44  *
  45  * @return a new cbuf object, NULL on error
  46  */
  47 cbuf* cbuf_new(const void* talloc_ctx);
  48
  49 /**
  50  * Create a copy of a character buffer.
  51  *
  52  * @param b the cbuf to copy
  53  * @return a new cbuf object, NULL on error
  54  */
  55 cbuf* cbuf_copy(const cbuf* b);
  56
  57 /**
  58  * Delete a character buffer.
  59  * This invalidates b and free's the memory allocated.
  60  * @warning don't talloc_free b directly, however freeing
  61  *          the parent works as expected
  62  * @param b the cbuf to delete
  63  */
  64 void  cbuf_delete(cbuf* b);
  65
  66 /**
  67  * Reset the buffer to initial state.
  68  * Set the write positon to the start of buffer, effectivly
  69  * clearing its contents. Doesn't free memory.
  70  *
  71  * @param b the buffer to clear
  72  *
  73  * @return b
  74  */
  75 cbuf* cbuf_clear(cbuf* b);
  76
  77 /**
  78  * Swap the contents of two buffers in O(1).
  79  *
  80  * @param b1 a character buffer
  81  * @param b2 another character buffer
  82  */
  83 void cbuf_swap(cbuf* b1, cbuf* b2);
  84
  85 /**
  86  * Swap the contents of a buffer with a talloced string.
  87  *
  88  * @param b a character buffer
  89  * @param ptr a pointer to a talloced string
  90  * @param len size of string, -1 means strlen(*ptr)
  91  *
  92  * @return b
  93  */
  94 cbuf* cbuf_swapptr(cbuf* b, char** ptr, size_t len);
  95
  96 /**
  97  * Let a character buffer takeover the contents of another.
  98  * This is equivalent to @code
  99  *   cbuf_swap(b1, b2);
 100  *   cbuf_delete(b2);
 101  * @endcode
 102  * @param b1 the destination
 103  * @param b2 the victim
 104  *
 105  * @return b1
 106  */
 107 cbuf* cbuf_takeover(cbuf* b1, cbuf* b2);
 108
 109 /**
 110  * Resize a character buffer.
 111  * This may free allocated memory.
 112  *
 113  * @param b the character buffer.
 114  * @param size the new size
 115  *
 116  * @return b, NULL on error
 117  */
 118 cbuf* cbuf_resize(cbuf* b, size_t size);
 119
 120 /**
 121  * Reserve space in a character buffer.
 122  * Assert there are at least len bytes following the current write position.
 123  *
 124  * @param b a character buffer
 125  * @param len number of bytes to reserve.
 126  *
 127  * @return a pointer to the current write position, NULL on error
 128  */
 129 char* cbuf_reserve(cbuf* b, size_t len);
 130
 131 /**
 132  * Put a character into the buffer.
 133  *
 134  * @param b a charcter buffer, may be NULL.
 135  * @param c a character
 136  * @return number of charcters written ((b==NULL) ? 0 : 1)
 137  *
 138  * @retval -1 on error
 139  */
 140 int cbuf_putc(cbuf* b, char c);
 141
 142 /**
 143  * Put a string into the buffer.
 144  *
 145  * @param b a character buffer, may be NULL
 146  * @param str a string
 147  * @param len number of bytes to write, -1 means strlen(str)
 148  *
 149  * @return number of characters written, -1 on error
 150  */
 151 int cbuf_puts(cbuf* b, const char* str, size_t len);
 152
 153 /* /\** */
 154 /*  * Put a string into the buffer, changing case. */
 155 /*  * */
 156 /*  * @param b a character buffer, may be NULL */
 157 /*  * @param str a string */
 158 /*  * @param len number of bytes to write, -1 means strlen(str) */
 159 /*  * @param c   a character specifying case: */
 160 /*  *        @li 'U' upper case */
 161 /*  *        @li 'L' lower case */
 162 /*  *        @li 'T' title case */
 163 /*  *        @li 'P' preserve case */
 164 /*  * @return number of characters written, -1 on error */
 165 /*  *\/ */
 166 /* int cbuf_puts_case(cbuf* b, const char* str, size_t len, char c); */
 167
 168
 169
 170 /**
 171  * Put a uint32 into the buffer.
 172  * Write in little endian order.
 173  *
 174  * @param b a character buffer, may be NULL
 175  * @param u an uint32
 176  *
 177  * @return number of characters written, -1 on error
 178  */
 179 int cbuf_putdw(cbuf* b, uint32_t u);
 180
 181 /**
 182  * Print formated to a character buffer.
 183  *
 184  * @param b a charcter buffer
 185  * @param fmt a printf format string
 186  *
 187  * @return number of characters written, negative on error
 188  */
 189 int cbuf_printf(cbuf* b, const char* fmt, ...);
 190
 191
 192 /**
 193  * Get the current write position.
 194  *
 195  * @param b a character buffer.
 196  *
 197  * @return index of the next charcter to write.
 198  */
 199 size_t cbuf_getpos(const cbuf* b);
 200
 201 /**
 202  * Set the current write position of a buffer.
 203  * Invalidates the buffer contents from on the new position.
 204  *
 205  * @param b a charcter buffer
 206  * @param pos a position obtained by cbuf_getpos
 207  */
 208 void cbuf_setpos(cbuf* b, size_t pos);
 209
 210 /**
 211  * Get the buffer contents
 212  * starting at idx.
 213  * @pre @code idx <= cbuf_getpos(b) @endcode
 214  * @param b a character buffer
 215  * @param idx a position obtained by cbuf_getpos
 216  *
 217  * @return a NUL terminated string
 218  */
 219 char* cbuf_gets(cbuf* b, size_t idx);
 220
 221 /**
 222  * Print quoted string to stream.
 223  *
 224  * @todo check for ssputc failure
 225  * @see srprs_quoted_string
 226  *
 227  * @param[out] ost outstream
 228  * @param[in]  s '\0' terminated string of printable characters.
 229  *
 230  * @return numner of bytes written, -1 on error
 231  */
 232 int cbuf_print_quoted_string(cbuf* ost, const char* s);
 233
 234 /**
 235  * Print quoted string to stream.
 236  * Escapes nonprintable characters.
 237  *
 238  * @todo check for ssputc failure
 239  * @see srprs_quoted
 240  *
 241  * @param[out] ost outstream
 242  * @param[in]  s string of bytes
 243  * @param[in]  len number of bytes
 244  *
 245  * @return numner of bytes written, -1 on error
 246  */
 247 int cbuf_print_quoted(cbuf* ost, const char* s, size_t len);
 248
 249
 250 #endif /*__CBUF_H*/