2 * Samba Unix/Linux SMB client library
3 * Copyright (C) Gregor Beck 2010
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.
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.
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/>.
21 * @author Gregor Beck <gb@sernet.de>
24 * @brief A talloced character buffer.
26 * A cbuf carries a write position and keeps track of its size.
38 typedef struct cbuf cbuf
;
41 * Create a new character buffer.
43 * @param talloc_ctx the talloc parent
45 * @return a new cbuf object, NULL on error
47 cbuf
* cbuf_new(const void* talloc_ctx
);
50 * Create a copy of a character buffer.
52 * @param b the cbuf to copy
53 * @return a new cbuf object, NULL on error
55 cbuf
* cbuf_copy(const cbuf
* b
);
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
64 void cbuf_delete(cbuf
* b
);
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.
71 * @param b the buffer to clear
75 cbuf
* cbuf_clear(cbuf
* b
);
78 * Swap the contents of two buffers in O(1).
80 * @param b1 a character buffer
81 * @param b2 another character buffer
83 void cbuf_swap(cbuf
* b1
, cbuf
* b2
);
86 * Swap the contents of a buffer with a talloced string.
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)
94 cbuf
* cbuf_swapptr(cbuf
* b
, char** ptr
, size_t len
);
97 * Let a character buffer takeover the contents of another.
98 * This is equivalent to @code
102 * @param b1 the destination
103 * @param b2 the victim
107 cbuf
* cbuf_takeover(cbuf
* b1
, cbuf
* b2
);
110 * Resize a character buffer.
111 * This may free allocated memory.
113 * @param b the character buffer.
114 * @param size the new size
116 * @return b, NULL on error
118 cbuf
* cbuf_resize(cbuf
* b
, size_t size
);
121 * Reserve space in a character buffer.
122 * Assert there are at least len bytes following the current write position.
124 * @param b a character buffer
125 * @param len number of bytes to reserve.
127 * @return a pointer to the current write position, NULL on error
129 char* cbuf_reserve(cbuf
* b
, size_t len
);
132 * Put a character into the buffer.
134 * @param b a charcter buffer, may be NULL.
135 * @param c a character
136 * @return number of charcters written ((b==NULL) ? 0 : 1)
138 * @retval -1 on error
140 int cbuf_putc(cbuf
* b
, char c
);
143 * Put a string into the buffer.
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)
149 * @return number of characters written, -1 on error
151 int cbuf_puts(cbuf
* b
, const char* str
, size_t len
);
154 /* * Put a string into the buffer, changing case. */
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 */
166 /* int cbuf_puts_case(cbuf* b, const char* str, size_t len, char c); */
171 * Put a uint32 into the buffer.
172 * Write in little endian order.
174 * @param b a character buffer, may be NULL
177 * @return number of characters written, -1 on error
179 int cbuf_putdw(cbuf
* b
, uint32_t u
);
182 * Print formated to a character buffer.
184 * @param b a charcter buffer
185 * @param fmt a printf format string
187 * @return number of characters written, negative on error
189 int cbuf_printf(cbuf
* b
, const char* fmt
, ...);
193 * Get the current write position.
195 * @param b a character buffer.
197 * @return index of the next charcter to write.
199 size_t cbuf_getpos(const cbuf
* b
);
202 * Set the current write position of a buffer.
203 * Invalidates the buffer contents from on the new position.
205 * @param b a charcter buffer
206 * @param pos a position obtained by cbuf_getpos
208 void cbuf_setpos(cbuf
* b
, size_t pos
);
211 * Get the buffer contents
213 * @pre @code idx <= cbuf_getpos(b) @endcode
214 * @param b a character buffer
215 * @param idx a position obtained by cbuf_getpos
217 * @return a NUL terminated string
219 char* cbuf_gets(cbuf
* b
, size_t idx
);
222 * Print quoted string to stream.
224 * @todo check for ssputc failure
225 * @see srprs_quoted_string
227 * @param[out] ost outstream
228 * @param[in] s '\0' terminated string of printable characters.
230 * @return numner of bytes written, -1 on error
232 int cbuf_print_quoted_string(cbuf
* ost
, const char* s
);
235 * Print quoted string to stream.
236 * Escapes nonprintable characters.
238 * @todo check for ssputc failure
241 * @param[out] ost outstream
242 * @param[in] s string of bytes
243 * @param[in] len number of bytes
245 * @return numner of bytes written, -1 on error
247 int cbuf_print_quoted(cbuf
* ost
, const char* s
, size_t len
);