Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/buffer_requirements.md

raw
1 BUFFER Requirements
2 ================
3
4 ## Overview
5
6 The BUFFER object encapsulastes a unsigned char* variable.
7
8 ## Exposed API
9 ```c
10 typedef void* BUFFER_HANDLE;
11
12 extern BUFFER_HANDLE BUFFER_new(void);
13
14 extern void BUFFER_delete(BUFFER_HANDLE handle);
15 extern BUFFER_HANDLE BUFFER_create(const unsigned char* source, size_t size);
16 extern BUFFER_HANDLE BUFFER_create_with_size(size_t buff_size)
17 extern int BUFFER_pre_build(BUFFER_HANDLE handle, size_t size);
18 extern int BUFFER_build(BUFFER_HANDLE handle, const unsigned char* source, size_t size);
19 extern int BUFFER_unbuild(BUFFER_HANDLE handle);
20 extern int BUFFER_enlarge(BUFFER_HANDLE handle, size_t enlargeSize);
21 extern int BUFFER_content(BUFFER_HANDLE handle, const unsigned char** content);
22 extern int BUFFER_size(BUFFER_HANDLE handle, size_t* size);
23 extern int BUFFER_append(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2);
24 extern int BUFFER_prepend(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2);
25 extern unsigned char* BUFFER_u_char(BUFFER_HANDLE handle);
26 extern size_t BUFFER_length(BUFFER_HANDLE handle);
27 extern BUFFER_HANDLE BUFFER_clone(BUFFER_HANDLE handle);
28 extern int BUFFER_fill(BUFFER_HANDLE handle, unsigned char fill_char);
29
30 ```
31
32 ### BUFFER_new
33 ```c
34 BUFFER_HANDLE BUFFER_new(void)
35 ```
36
37 **SRS_BUFFER_07_001: [** BUFFER_new shall allocate a BUFFER_HANDLE that will contain a NULL unsigned char*. **]**
38
39 ### BUFFER_create
40
41 ```c
42 extern BUFFER_HANDLE BUFFER_create(const unsigned char* source, size_t size);
43 ```
44
45 BUFFER_create creates a new buffer from the memory at source, having size "size".
46
47 **SRS_BUFFER_02_001: [** If source is NULL then BUFFER_create shall return NULL. **]**
48
49 **SRS_BUFFER_02_002: [** Otherwise, BUFFER_create shall allocate memory to hold size bytes and shall copy from source size bytes into the newly allocated memory. **]**
50
51 **SRS_BUFFER_02_003: [** If allocating memory fails, then BUFFER_create shall return NULL. **]**
52
53 **SRS_BUFFER_02_004: [** Otherwise, BUFFER_create shall return a non-NULL handle. **]**
54
55 ### BUFFER_create_with_size
56
57
58
59 ```c
60 extern BUFFER_HANDLE BUFFER_create_with_size(size_t buff_size)
61 ```
62
63 **SRS_BUFFER_07_029: [** BUFFER_create_with_size shall create a BUFFER_HANDLE with a pre allocated underlying buffer size. **]**
64
65 **SRS_BUFFER_07_030: [** If buff_size is 0 BUFFER_create_with_size shall create a valid non-NULL handle of zero size. **]**
66
67 **SRS_BUFFER_07_031: [** BUFFER_create_with_size shall allocate a buffer of buff_size. **]**
68
69 **SRS_BUFFER_07_032: [** If allocating memory fails, then BUFFER_create_with_size shall return NULL. **]**
70
71 **SRS_BUFFER_07_033: [** Otherwise, BUFFER_create_with_size shall return a non-NULL handle. **]**
72
73 ### BUFFER_delete
74
75 ```c
76 void BUFFER_delete(BUFFER_HANDLE handle)
77 ```
78
79 **SRS_BUFFER_07_003: [** BUFFER_delete shall delete the data associated with the BUFFER_HANDLE along with the Buffer. **]**
80
81 **SRS_BUFFER_07_004: [** BUFFER_delete shall not delete any BUFFER_HANDLE that is NULL. **]**
82
83 ### BUFFER_pre_build
84 ```c
85 int BUFFER_pre_build(BUFFER_HANDLE handle, size_t size)
86 ```
87
88 **SRS_BUFFER_07_005: [** BUFFER_pre_build allocates size_t bytes of BUFFER_HANDLE and returns zero on success. **]**
89
90 **SRS_BUFFER_07_006: [** If handle is NULL or size is 0 then BUFFER_pre_build shall return a nonzero value. **]**
91
92 **SRS_BUFFER_07_007: [** BUFFER_pre_build shall return nonzero if the buffer has been previously allocated and is not NULL. **]**
93
94 **SRS_BUFFER_07_013: [** BUFFER_pre_build shall return nonzero if any error is encountered. **]**
95
96 ### BUFFER_build
97
98 ```c
99 int BUFFER_build(BUFFER_HANDLE handle, const unsigned char* source, size_t size)
100 ```
101
102 **SRS_BUFFER_07_008: [** BUFFER_build allocates size_t bytes, copies the unsigned char* into the buffer and returns zero on success. **]**
103
104 **SRS_BUFFER_07_009: [** BUFFER_build shall return nonzero if handle is NULL **]**
105
106 **SRS_BUFFER_01_001: [** If size is positive and source is NULL, BUFFER_build shall return nonzero **]**
107
108 **SRS_BUFFER_01_002: [** The size argument can be zero, in which case the underlying buffer held by the buffer instance shall be freed. **]**
109
110 **SRS_BUFFER_01_003: [** If size is zero, source can be NULL. **]**
111
112 **SRS_BUFFER_07_010: [** BUFFER_build shall return nonzero if any error is encountered. **]**
113
114 **SRS_BUFFER_07_011: [** BUFFER_build shall overwrite previous contents if the buffer has been previously allocated. **]**
115
116 ### BUFFER_append_build
117
118 ```c
119 int BUFFER_append_build(BUFFER_HANDLE handle, const unsigned char* source, size_t size)
120 ```
121
122 **SRS_BUFFER_07_029: [** `BUFFER_append_build` shall return nonzero if handle or source are NULL or if size is 0. **]**
123
124 **SRS_BUFFER_07_030: [** if handle->buffer is NULL `BUFFER_append_build` shall allocate the a buffer of size bytes... **]**
125
126 **SRS_BUFFER_07_031: [** ... and copy the contents of source to handle->buffer. **]**
127
128 **SRS_BUFFER_07_032: [** if handle->buffer is not NULL `BUFFER_append_build` shall realloc the buffer to be the handle->size + size **]**
129
130 **SRS_BUFFER_07_033: [** ... and copy the contents of source to the end of the buffer. **]**
131
132 **SRS_BUFFER_07_034: [** On success `BUFFER_append_build` shall return 0 **]**
133
134 **SRS_BUFFER_07_035: [** If any error is encountered `BUFFER_append_build` shall return a non-null value. **]**
135
136 ### BUFFER_unbuild
137
138 ```c
139 int BUFFER_unbuild(BUFFER_HANDLE b)
140 ```
141
142 **SRS_BUFFER_07_012: [** BUFFER_unbuild shall clear the underlying unsigned char* data associated with the BUFFER_HANDLE this will return zero on success. **]**
143
144 **SRS_BUFFER_07_014: [** BUFFER_unbuild shall return a nonzero value if BUFFER_HANDLE is NULL. **]**
145
146 **SRS_BUFFER_07_015: [** BUFFER_unbuild shall always return success if the unsigned char* referenced by BUFFER_HANDLE is NULL. **]**
147
148 ### BUFFER_enlarge
149
150 ```c
151 int BUFFER_enlarge(BUFFER_HANDLE handle, size_t enlargeSize)
152 ```
153
154 **SRS_BUFFER_07_016: [** BUFFER_enlarge shall increase the size of the unsigned char* referenced by BUFFER_HANDLE. **]**
155
156 **SRS_BUFFER_07_017: [** BUFFER_enlarge shall return a nonzero result if any parameters are NULL or zero. **]**
157
158 **SRS_BUFFER_07_018: [** BUFFER_enlarge shall return a nonzero result if any error is encountered. **]**
159
160 ### BUFFER_shrink
161
162 ```c
163 int BUFFER_shrink(BUFFER_HANDLE handle, size_t decreaseSize, bool fromEnd)
164 ```
165
166 **SRS_BUFFER_07_036: [** if handle is NULL, `BUFFER_shrink` shall return a non-null value **]**
167
168 **SRS_BUFFER_07_037: [** If decreaseSize is equal zero, `BUFFER_shrink` shall return a non-null value **]**
169
170 **SRS_BUFFER_07_038: [** If decreaseSize is less than the size of the buffer, `BUFFER_shrink` shall return a non-null value **]**
171
172 **SRS_BUFFER_07_039: [** `BUFFER_shrink` shall allocate a temporary buffer of existing buffer size minus decreaseSize. **]**
173
174 **SRS_BUFFER_07_040: [** if the fromEnd variable is true, `BUFFER_shrink` shall remove the end of the buffer of size decreaseSize. **]**
175
176 **SRS_BUFFER_07_041: [** if the fromEnd variable is false, `BUFFER_shrink` shall remove the beginning of the buffer of size decreaseSize. **]**
177
178 **SRS_BUFFER_07_042: [** If a failure is encountered, `BUFFER_shrink` shall return a non-null value **]**
179
180 **SRS_BUFFER_07_043: [** If the decreaseSize is equal the buffer size , `BUFFER_shrink` shall deallocate the buffer and set the size to zero. **]**
181 ### BUFFER_content
182
183 ```c
184 int BUFFER_content(BUFFER_HANDLE handle, unsigned char** content)
185 ```
186
187 **SRS_BUFFER_07_019: [** BUFFER_content shall return the data contained within the BUFFER_HANDLE. **]**
188
189 **SRS_BUFFER_07_020: [** If the handle and/or content*is NULL BUFFER_content shall return nonzero. **]**
190
191 ### BUFFER_size
192 ```c
193 int BUFFER_size(BUFFER_HANDLE b, size_t* size)
194 ```
195
196 **SRS_BUFFER_07_021: [** BUFFER_size shall place the size of the associated buffer in the size variable and return zero on success. **]**
197
198 **SRS_BUFFER_07_022: [** BUFFER_size shall return a nonzero value for any error that is encountered. **]**
199
200 ### BUFFER_append
201 ```c
202 int BUFFER_append(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2)
203 ```
204
205 **SRS_BUFFER_07_024: [** BUFFER_append concatenates b2 onto b1 without modifying b2 and shall return zero on success. **]**
206
207 **SRS_BUFFER_07_023: [** BUFFER_append shall return a nonzero upon any error that is encountered. **]**
208
209 ### BUFFER_prepend
210 ```c
211 int BUFFER_prepend(BUFFER_HANDLE handle1, BUFFER_HANDLE handle2)
212 ```
213
214 **SRS_BUFFER_01_004: [** BUFFER_prepend concatenates handle1 onto handle2 without modifying handle1 and shall return zero on success. **]**
215
216 **SRS_BUFFER_01_005: [** BUFFER_prepend shall return a non-zero upon value any error that is encountered. **]**
217
218 ### BUFFER_fill
219
220 ```c
221 extern int BUFFER_fill(BUFFER_HANDLE handle, unsigned char fill_char);
222 ```
223
224 **SRS_BUFFER_07_001: [** `BUFFER_fill` shall fill the supplied `BUFFER_HANDLE` with the supplied fill character. **]**
225
226 **SRS_BUFFER_07_002: [** If `handle` is NULL `BUFFER_fill` shall return a non-zero value. **]**
227
228 ### BUFFER_u_char
229
230 ```c
231 unsigned char* BUFFER_u_char(BUFFER_HANDLE handle)
232 ```
233
234 **SRS_BUFFER_07_025: [** BUFFER_u_char shall return a pointer to the underlying unsigned char*. **]**
235
236 **SRS_BUFFER_07_026: [** BUFFER_u_char shall return NULL for any error that is encountered. **]**
237
238 ### BUFFER_length
239
240 ```c
241 size_t BUFFER_length(BUFFER_HANDLE handle)
242 ```
243
244 **SRS_BUFFER_07_027: [** BUFFER_length shall return the size of the underlying buffer. **]**
245
246 **SRS_BUFFER_07_028: [** BUFFER_length shall return zero for any error that is encountered. **]**