summaryrefslogtreecommitdiffstats
path: root/source3/lib/cbuf.h
blob: 90318ec7a992c92728ef3883b1750a1ed26fb5e6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
/*
 * 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 '\0' terminated string of printable characters.
 *
 * @return numner of bytes written, -1 on error
 */
int cbuf_print_quoted_string(cbuf* ost, const char* s);

/**
 * Print quoted string to stream.
 * Escapes nonprintable characters.
 *
 * @todo check for ssputc failure
 * @see srprs_quoted
 *
 * @param[out] ost outstream
 * @param[in]  s string of bytes
 * @param[in]  len number of bytes
 *
 * @return numner of bytes written, -1 on error
 */
int cbuf_print_quoted(cbuf* ost, const char* s, size_t len);


#endif /*__CBUF_H*/