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 struct cbuf;
  33 typedef struct cbuf cbuf;
  34
  35 /**
  36  * Create a new character buffer.
  37  *
  38  * @param talloc_ctx the talloc parent
  39  *
  40  * @return a new cbuf object, NULL on error
  41  */
  42 cbuf* cbuf_new(const void* talloc_ctx);
  43
  44 /**
  45  * Create a copy of a character buffer.
  46  *
  47  * @param b the cbuf to copy
  48  * @return a new cbuf object, NULL on error
  49  */
  50 cbuf* cbuf_copy(const cbuf* b);
  51
  52 /**
  53  * Delete a character buffer.
  54  * This invalidates b and free's the memory allocated.
  55  * @warning don't talloc_free b directly, however freeing
  56  *          the parent works as expected
  57  * @param b the cbuf to delete
  58  */
  59 void  cbuf_delete(cbuf* b);
  60
  61 /**
  62  * Reset the buffer to initial state.
  63  * Set the write position to the start of buffer, effectivly
  64  * clearing its contents. Doesn't free memory.
  65  *
  66  * @param b the buffer to clear
  67  *
  68  * @return b
  69  */
  70 cbuf* cbuf_clear(cbuf* b);
  71
  72 /**
  73  * Swap the contents of two buffers in O(1).
  74  *
  75  * @param b1 a character buffer
  76  * @param b2 another character buffer
  77  */
  78 void cbuf_swap(cbuf* b1, cbuf* b2);
  79
  80 /**
  81  * Swap the contents of a buffer with a talloced string.
  82  *
  83  * @param b a character buffer
  84  * @param ptr a pointer to a talloced string
  85  * @param len size of string, -1 means strlen(*ptr)
  86  *
  87  * @return b
  88  */
  89 cbuf* cbuf_swapptr(cbuf* b, char** ptr, size_t len);
  90
  91 /**
  92  * Let a character buffer takeover the contents of another.
  93  * This is equivalent to @code
  94  *   cbuf_swap(b1, b2);
  95  *   cbuf_delete(b2);
  96  * @endcode
  97  * @param b1 the destination
  98  * @param b2 the victim
  99  *
 100  * @return b1
 101  */
 102 cbuf* cbuf_takeover(cbuf* b1, cbuf* b2);
 103
 104 /**
 105  * Resize a character buffer.
 106  * This may free allocated memory.
 107  *
 108  * @param b the character buffer.
 109  * @param size the new size
 110  *
 111  * @return b, NULL on error
 112  */
 113 cbuf* cbuf_resize(cbuf* b, size_t size);
 114
 115 /**
 116  * Reserve space in a character buffer.
 117  * Assert there are at least len bytes following the current write position.
 118  *
 119  * @param b a character buffer
 120  * @param len number of bytes to reserve.
 121  *
 122  * @return a pointer to the current write position, NULL on error
 123  */
 124 char* cbuf_reserve(cbuf* b, size_t len);
 125
 126 /**
 127  * Put a character into the buffer.
 128  *
 129  * @param b a character buffer, may be NULL.
 130  * @param c a character
 131  * @return number of characters written ((b==NULL) ? 0 : 1)
 132  *
 133  * @retval -1 on error
 134  */
 135 int cbuf_putc(cbuf* b, char c);
 136
 137 /**
 138  * Put a string into the buffer.
 139  *
 140  * @param b a character buffer, may be NULL
 141  * @param str a string
 142  * @param len number of bytes to write, -1 means strlen(str)
 143  *
 144  * @return number of characters written, -1 on error
 145  */
 146 int cbuf_puts(cbuf* b, const char* str, size_t len);
 147
 148 /* /\** */
 149 /*  * Put a string into the buffer, changing case. */
 150 /*  * */
 151 /*  * @param b a character buffer, may be NULL */
 152 /*  * @param str a string */
 153 /*  * @param len number of bytes to write, -1 means strlen(str) */
 154 /*  * @param c   a character specifying case: */
 155 /*  *        @li 'U' upper case */
 156 /*  *        @li 'L' lower case */
 157 /*  *        @li 'T' title case */
 158 /*  *        @li 'P' preserve case */
 159 /*  * @return number of characters written, -1 on error */
 160 /*  *\/ */
 161 /* int cbuf_puts_case(cbuf* b, const char* str, size_t len, char c); */
 162
 163
 164
 165 /**
 166  * Put a uint32 into the buffer.
 167  * Write in little endian order.
 168  *
 169  * @param b a character buffer, may be NULL
 170  * @param u an uint32
 171  *
 172  * @return number of characters written, -1 on error
 173  */
 174 int cbuf_putdw(cbuf* b, uint32_t u);
 175
 176 /**
 177  * Print formatted to a character buffer.
 178  *
 179  * @param b a character buffer
 180  * @param fmt a printf format string
 181  *
 182  * @return number of characters written, negative on error
 183  */
 184 int cbuf_printf(cbuf* b, const char* fmt, ...) PRINTF_ATTRIBUTE(2,3);
 185
 186
 187 /**
 188  * Get the current write position.
 189  *
 190  * @param b a character buffer.
 191  *
 192  * @return index of the next character to write.
 193  */
 194 size_t cbuf_getpos(const cbuf* b);
 195
 196 /**
 197  * Set the current write position of a buffer.
 198  * Invalidates the buffer contents from on the new position.
 199  *
 200  * @param b a character buffer
 201  * @param pos a position obtained by cbuf_getpos
 202  */
 203 void cbuf_setpos(cbuf* b, size_t pos);
 204
 205 /**
 206  * Get the buffer contents
 207  * starting at idx.
 208  * @pre @code idx <= cbuf_getpos(b) @endcode
 209  * @param b a character buffer
 210  * @param idx a position obtained by cbuf_getpos
 211  *
 212  * @return a NUL terminated string
 213  */
 214 char* cbuf_gets(cbuf* b, size_t idx);
 215
 216 /**
 217  * Print quoted string to stream.
 218  *
 219  * @todo check for ssputc failure
 220  * @see srprs_quoted_string
 221  *
 222  * @param[out] ost outstream
 223  * @param[in]  s '\0' terminated string of printable characters.
 224  *
 225  * @return number of bytes written, -1 on error
 226  */
 227 int cbuf_print_quoted_string(cbuf* ost, const char* s);
 228
 229 /**
 230  * Print quoted string to stream.
 231  * Escapes nonprintable characters.
 232  *
 233  * @todo check for ssputc failure
 234  * @see srprs_quoted
 235  *
 236  * @param[out] ost outstream
 237  * @param[in]  s string of bytes
 238  * @param[in]  len number of bytes
 239  *
 240  * @return number of bytes written, -1 on error
 241  */
 242 int cbuf_print_quoted(cbuf* ost, const char* s, size_t len);
 243
 244
 245 #endif /*__CBUF_H*/