wafsamba.samba_abi: Refactor abi_write_vscript to take file argument.
[Samba/bb.git] / source3 / lib / cbuf.h
blobb9c555282693ebb3960eb3b366721f89c080872d
1 /*
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/>.
19 /**
20 * @file cbuf.h
21 * @author Gregor Beck <gb@sernet.de>
22 * @date Aug 2010
24 * @brief A talloced character buffer.
26 * A cbuf carries a write position and keeps track of its size.
29 #ifndef __CBUF_H
30 #define __CBUF_H
32 struct cbuf;
33 typedef struct cbuf cbuf;
35 /**
36 * Create a new character buffer.
38 * @param talloc_ctx the talloc parent
40 * @return a new cbuf object, NULL on error
42 cbuf* cbuf_new(const void* talloc_ctx);
44 /**
45 * Create a copy of a character buffer.
47 * @param b the cbuf to copy
48 * @return a new cbuf object, NULL on error
50 cbuf* cbuf_copy(const cbuf* b);
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
59 void cbuf_delete(cbuf* b);
61 /**
62 * Reset the buffer to initial state.
63 * Set the write positon to the start of buffer, effectivly
64 * clearing its contents. Doesn't free memory.
66 * @param b the buffer to clear
68 * @return b
70 cbuf* cbuf_clear(cbuf* b);
72 /**
73 * Swap the contents of two buffers in O(1).
75 * @param b1 a character buffer
76 * @param b2 another character buffer
78 void cbuf_swap(cbuf* b1, cbuf* b2);
80 /**
81 * Swap the contents of a buffer with a talloced string.
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)
87 * @return b
89 cbuf* cbuf_swapptr(cbuf* b, char** ptr, size_t len);
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
100 * @return b1
102 cbuf* cbuf_takeover(cbuf* b1, cbuf* b2);
105 * Resize a character buffer.
106 * This may free allocated memory.
108 * @param b the character buffer.
109 * @param size the new size
111 * @return b, NULL on error
113 cbuf* cbuf_resize(cbuf* b, size_t size);
116 * Reserve space in a character buffer.
117 * Assert there are at least len bytes following the current write position.
119 * @param b a character buffer
120 * @param len number of bytes to reserve.
122 * @return a pointer to the current write position, NULL on error
124 char* cbuf_reserve(cbuf* b, size_t len);
127 * Put a character into the buffer.
129 * @param b a charcter buffer, may be NULL.
130 * @param c a character
131 * @return number of charcters written ((b==NULL) ? 0 : 1)
133 * @retval -1 on error
135 int cbuf_putc(cbuf* b, char c);
138 * Put a string into the buffer.
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)
144 * @return number of characters written, -1 on error
146 int cbuf_puts(cbuf* b, const char* str, size_t len);
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); */
166 * Put a uint32 into the buffer.
167 * Write in little endian order.
169 * @param b a character buffer, may be NULL
170 * @param u an uint32
172 * @return number of characters written, -1 on error
174 int cbuf_putdw(cbuf* b, uint32_t u);
177 * Print formated to a character buffer.
179 * @param b a charcter buffer
180 * @param fmt a printf format string
182 * @return number of characters written, negative on error
184 int cbuf_printf(cbuf* b, const char* fmt, ...);
188 * Get the current write position.
190 * @param b a character buffer.
192 * @return index of the next charcter to write.
194 size_t cbuf_getpos(const cbuf* b);
197 * Set the current write position of a buffer.
198 * Invalidates the buffer contents from on the new position.
200 * @param b a charcter buffer
201 * @param pos a position obtained by cbuf_getpos
203 void cbuf_setpos(cbuf* b, size_t pos);
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
212 * @return a NUL terminated string
214 char* cbuf_gets(cbuf* b, size_t idx);
217 * Print quoted string to stream.
219 * @todo check for ssputc failure
220 * @see srprs_quoted_string
222 * @param[out] ost outstream
223 * @param[in] s '\0' terminated string of printable characters.
225 * @return numner of bytes written, -1 on error
227 int cbuf_print_quoted_string(cbuf* ost, const char* s);
230 * Print quoted string to stream.
231 * Escapes nonprintable characters.
233 * @todo check for ssputc failure
234 * @see srprs_quoted
236 * @param[out] ost outstream
237 * @param[in] s string of bytes
238 * @param[in] len number of bytes
240 * @return numner of bytes written, -1 on error
242 int cbuf_print_quoted(cbuf* ost, const char* s, size_t len);
245 #endif /*__CBUF_H*/