Debian Codegraph @

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

raw
1 # constbuffer_array_requirements
2 ================
3
4 ## Overview
5
6 `constbuffer_array` is a module that stiches several `CONSTBUFFER_HANDLE`s together. `constbuffer_array` can add/remove a `CONSTBUFFER_HANDLE` at the beginning (front) of the already constructed stitch. `constbuffer_array` can merge with another `constbuffer_array` by appending the contents of one array to the other.
7
8 `CONSTBUFFER_ARRAY_HANDLE`s are immutable, that is, adding/removing a `CONSTBUFFER_HANDLE` to/from an existing `CONSTBUFFER_ARRAY_HANDLE` will result in a new `CONSTBUFFER_ARRAY_HANDLE`.
9
10 ## Exposed API
11
12 ```c
13 typedef struct CONSTBUFFER_ARRAY_HANDLE_DATA_TAG* CONSTBUFFER_ARRAY_HANDLE;
14
15 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create, const CONSTBUFFER_HANDLE*, buffers, uint32_t, buffer_count);
16 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create_with_move_buffers, CONSTBUFFER_HANDLE*, buffers, uint32_t, buffer_count);
17 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create_empty);
18 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create_from_array_array, const CONSTBUFFER_ARRAY_HANDLE*, buffer_arrays, uint32_t, buffer_array_count);
19
20 MOCKABLE_FUNCTION(, void, constbuffer_array_inc_ref, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle);
21 MOCKABLE_FUNCTION(, void, constbuffer_array_dec_ref, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle);
22
23 /*add in front*/
24 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_add_front, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, CONSTBUFFER_HANDLE, constbuffer_handle);
25
26 /*remove front*/
27 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_remove_front, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, CONSTBUFFER_HANDLE *const_buffer_handle);
28
29 /* getters */
30 MOCKABLE_FUNCTION(, int, constbuffer_array_get_buffer_count, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t*, buffer_count);
31 MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, constbuffer_array_get_buffer, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t, buffer_index);
32 MOCKABLE_FUNCTION(, const CONSTBUFFER*, constbuffer_array_get_buffer_content, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t, buffer_index);
33 MOCKABLE_FUNCTION(, int, constbuffer_array_get_all_buffers_size, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t*, all_buffers_size);
34 MOCKABLE_FUNCTION(, const CONSTBUFFER_HANDLE*, constbuffer_array_get_const_buffer_handle_array, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle);
35
36 /*compare*/
37 MOCKABLE_FUNCTION(, bool, CONSTBUFFER_ARRAY_HANDLE_contain_same, CONSTBUFFER_ARRAY_HANDLE, left, CONSTBUFFER_ARRAY_HANDLE, right);
38 ```
39
40 ### constbuffer_array_create
41
42 ```c
43 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create, const CONSTBUFFER_HANDLE*, buffers, uint32_t, buffer_count);
44 ```
45
46 `constbuffer_array_create` creates a new const buffer array made of the const buffers in `buffers`.
47
48 **SRS_CONSTBUFFER_ARRAY_01_009: [** `constbuffer_array_create` shall allocate memory for a new `CONSTBUFFER_ARRAY_HANDLE` that can hold `buffer_count` buffers. **]**
49
50 **SRS_CONSTBUFFER_ARRAY_01_010: [** `constbuffer_array_create` shall clone the buffers in `buffers` and store them. **]**
51
52 **SRS_CONSTBUFFER_ARRAY_01_011: [** On success `constbuffer_array_create` shall return a non-NULL handle. **]**
53
54 **SRS_CONSTBUFFER_ARRAY_01_012: [** If `buffers` is NULL and `buffer_count` is not 0, `constbuffer_array_create` shall fail and return NULL. **]**
55
56 **SRS_CONSTBUFFER_ARRAY_01_014: [** If any error occurs, `constbuffer_array_create` shall fail and return NULL. **]**
57
58 ### constbuffer_array_create_with_move_buffers
59
60 ```c
61 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create_with_move_buffers, CONSTBUFFER_HANDLE*, buffers, uint32_t, buffer_count);
62 ```
63
64 `constbuffer_array_create_with_move_buffers` creates a new const buffer array made of the const buffers in `buffers` with move memory semantics for `buffers`.
65
66 Note: `constbuffer_array_create_with_move_buffers` does not increment the reference count of the buffer handles in `buffers`.
67
68 **SRS_CONSTBUFFER_ARRAY_01_028: [** If `buffers` is `NULL` and `buffer_count` is not 0, `constbuffer_array_create_with_move_buffers` shall fail and return `NULL`. **]**
69
70 **SRS_CONSTBUFFER_ARRAY_01_029: [** Otherwise, `constbuffer_array_create_with_move_buffers` shall allocate memory for a new `CONSTBUFFER_ARRAY_HANDLE` that holds the const buffers in `buffers`. **]**
71
72 **SRS_CONSTBUFFER_ARRAY_01_031: [** On success `constbuffer_array_create_with_move_buffers` shall return a non-`NULL` handle. **]**
73
74 **SRS_CONSTBUFFER_ARRAY_01_030: [** If any error occurs, `constbuffer_array_create_with_move_buffers` shall fail and return `NULL`. **]**
75
76 ### constbuffer_array_create_empty
77
78 ```c
79 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create_empty);
80 ```
81
82 `constbuffer_array_create_empty` creates a new, empty CONSTBUFFER_ARRAY_HANDLE.
83
84 **SRS_CONSTBUFFER_ARRAY_02_004: [** `constbuffer_array_create_empty` shall allocate memory for a new `CONSTBUFFER_ARRAY_HANDLE`. **]**
85
86 **SRS_CONSTBUFFER_ARRAY_02_041: [** `constbuffer_array_create_empty` shall succeed and return a non-`NULL` value. **]**
87
88 **SRS_CONSTBUFFER_ARRAY_02_001: [** If are any failure is encountered, `constbuffer_array_create_empty` shall fail and return `NULL`. **]**
89
90 ### constbuffer_array_create_from_array_array
91
92 ```c
93 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_create_from_array_array, const CONSTBUFFER_ARRAY_HANDLE*, buffer_arrays, uint32_t, buffer_array_count);
94 ```
95
96 `constbuffer_array_create_from_array_array` creates a new const buffer array made of all the const buffers in `buffer_arrays`.
97
98 **SRS_CONSTBUFFER_ARRAY_42_009: [** If `buffer_arrays` is `NULL` and `buffer_array_count` is not 0 then `constbuffer_array_create_from_array_array` shall fail and return `NULL`. **]**
99
100 **SRS_CONSTBUFFER_ARRAY_42_001: [** If `buffer_arrays` is `NULL` or `buffer_array_count` is 0 then `constbuffer_array_create_from_array_array` shall create a new, empty `CONSTBUFFER_ARRAY_HANDLE`. **]**
101
102 **SRS_CONSTBUFFER_ARRAY_42_002: [** If any const buffer array in `buffer_arrays` is `NULL` then `constbuffer_array_create_from_array_array` shall fail and return `NULL`. **]**
103
104 **SRS_CONSTBUFFER_ARRAY_42_003: [** `constbuffer_array_create_from_array_array` shall allocate memory to hold all of the `CONSTBUFFER_HANDLES` from `buffer_arrays`. **]**
105
106 **SRS_CONSTBUFFER_ARRAY_42_004: [** `constbuffer_array_create_from_array_array` shall copy all of the `CONSTBUFFER_HANDLES` from each const buffer array in `buffer_arrays` to the newly constructed array by calling `CONSTBUFFER_IncRef`. **]**
107
108 **SRS_CONSTBUFFER_ARRAY_42_007: [** `constbuffer_array_create_from_array_array` shall succeed and return a non-`NULL` value. **]**
109
110 **SRS_CONSTBUFFER_ARRAY_42_008: [** If there are any failures then `constbuffer_array_create_from_array_array` shall fail and return `NULL`. **]**
111
112 ### constbuffer_array_inc_ref
113
114 ```c
115 MOCKABLE_FUNCTION(, void, constbuffer_array_inc_ref, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle);
116 ```
117
118 `constbuffer_array_inc_ref` increments the reference count for `constbuffer_array_handle`.
119
120 **SRS_CONSTBUFFER_ARRAY_01_017: [** If `constbuffer_array_handle` is `NULL` then `constbuffer_array_inc_ref` shall return. **]**
121
122 **SRS_CONSTBUFFER_ARRAY_01_018: [** Otherwise `constbuffer_array_inc_ref` shall increment the reference count for `constbuffer_array_handle`. **]**
123
124 ### constbuffer_array_dec_ref
125
126 ```c
127 MOCKABLE_FUNCTION(, void, constbuffer_array_dec_ref, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle);
128 ```
129
130 `constbuffer_array_dec_ref` decrements the reference count and frees all used resources if needed.
131
132 **SRS_CONSTBUFFER_ARRAY_02_039: [** If `constbuffer_array_handle` is `NULL` then `constbuffer_array_dec_ref` shall return. **]**
133
134 **SRS_CONSTBUFFER_ARRAY_01_016: [** Otherwise `constbuffer_array_dec_ref` shall decrement the reference count for `constbuffer_array_handle`. **]**
135
136 **SRS_CONSTBUFFER_ARRAY_02_038: [** If the reference count reaches 0, `constbuffer_array_dec_ref` shall free all used resources. **]**
137
138 ### constbuffer_array_add_front
139
140 ```c
141 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_add_front, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, CONSTBUFFER_HANDLE, constbuffer_handle);
142 ```
143
144 `constbuffer_array_add_front` adds a new `CONSTBUFFER_HANDLE` at the front of the already stored `CONSTBUFFER_HANDLE`s.
145
146 **SRS_CONSTBUFFER_ARRAY_02_006: [** If `constbuffer_array_handle` is `NULL` then `constbuffer_array_add_front` shall fail and return `NULL` **]**
147
148 **SRS_CONSTBUFFER_ARRAY_02_007: [** If `constbuffer_handle` is `NULL` then `constbuffer_array_add_front` shall fail and return `NULL` **]**
149
150 **SRS_CONSTBUFFER_ARRAY_02_042: [** `constbuffer_array_add_front` shall allocate enough memory to hold all of `constbuffer_array_handle` existing `CONSTBUFFER_HANDLE` and `constbuffer_handle`. **]**
151
152 **SRS_CONSTBUFFER_ARRAY_02_043: [** `constbuffer_array_add_front` shall copy `constbuffer_handle` and all of `constbuffer_array_handle` existing `CONSTBUFFER_HANDLE`. **]**
153
154 **SRS_CONSTBUFFER_ARRAY_02_044: [** `constbuffer_array_add_front` shall inc_ref all the `CONSTBUFFER_HANDLE` it had copied. **]**
155
156 **SRS_CONSTBUFFER_ARRAY_02_010: [** `constbuffer_array_add_front` shall succeed and return a non-`NULL` value. **]**
157
158 **SRS_CONSTBUFFER_ARRAY_02_011: [** If there any failures `constbuffer_array_add_front` shall fail and return `NULL`. **]**
159
160 ### constbuffer_array_remove_front
161
162 ```c
163 MOCKABLE_FUNCTION(, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_remove_front, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, CONSTBUFFER_HANDLE* const_buffer_handle);
164 ```
165
166 `constbuffer_array_remove_front` removes the front `CONSTBUFFER_HANDLE` and hands it over to the caller.
167
168 **SRS_CONSTBUFFER_ARRAY_02_012: [** If `constbuffer_array_handle` is `NULL` then `constbuffer_array_remove_front` shall fail and return `NULL`. **]**
169
170 **SRS_CONSTBUFFER_ARRAY_02_045: [** If `constbuffer_handle` is `NULL` then `constbuffer_array_remove_front` shall fail and return `NULL`. **]**
171
172 **SRS_CONSTBUFFER_ARRAY_02_013: [** If there is no front `CONSTBUFFER_HANDLE` then `constbuffer_array_remove_front` shall fail and return `NULL`. **]**
173
174 **SRS_CONSTBUFFER_ARRAY_02_002: [** `constbuffer_array_remove_front` shall fail when called on a newly constructed `CONSTBUFFER_ARRAY_HANDLE`. **]**
175
176 **SRS_CONSTBUFFER_ARRAY_02_046: [** `constbuffer_array_remove_front` shall allocate memory to hold all of `constbuffer_array_handle` `CONSTBUFFER_HANDLE`s except the front one. **]**
177
178 **SRS_CONSTBUFFER_ARRAY_02_047: [** `constbuffer_array_remove_front` shall copy all of `constbuffer_array_handle` `CONSTBUFFER_HANDLE`s except the front one. **]**
179
180 **SRS_CONSTBUFFER_ARRAY_02_048: [** `constbuffer_array_remove_front` shall inc_ref all the copied `CONSTBUFFER_HANDLE`s. **]**
181
182 **SRS_CONSTBUFFER_ARRAY_01_001: [** `constbuffer_array_remove_front` shall inc_ref the removed buffer. **]**
183
184 **SRS_CONSTBUFFER_ARRAY_02_049: [** `constbuffer_array_remove_front` shall succeed and return a non-`NULL` value. **]**
185
186 **SRS_CONSTBUFFER_ARRAY_02_036: [** If there are any failures then `constbuffer_array_remove_front` shall fail and return `NULL`. **]**
187
188 ### constbuffer_array_get_buffer_count
189
190 ```c
191 MOCKABLE_FUNCTION(, int, constbuffer_array_get_buffer_count, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t*, buffer_count);
192 ```
193
194 `constbuffer_array_get_buffer_count` gets the count of const buffers held by the const buffer array.
195
196 **SRS_CONSTBUFFER_ARRAY_01_002: [** On success, `constbuffer_array_get_buffer_count` shall return 0 and write the buffer count in `buffer_count`. **]**
197
198 **SRS_CONSTBUFFER_ARRAY_01_003: [** If `constbuffer_array_handle` is NULL, `constbuffer_array_get_buffer_count` shall fail and return a non-zero value. **]**
199
200 **SRS_CONSTBUFFER_ARRAY_01_004: [** If `buffer_count` is NULL, `constbuffer_array_get_buffer_count` shall fail and return a non-zero value. **]**
201
202 ### constbuffer_array_get_buffer
203
204 ```c
205 MOCKABLE_FUNCTION(, CONSTBUFFER_HANDLE, constbuffer_array_get_buffer, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t, buffer_index);
206 ```
207
208 `constbuffer_array_get_buffer` returns the buffer at the `buffer_index`-th given index in the array.
209
210 **SRS_CONSTBUFFER_ARRAY_01_005: [** On success, `constbuffer_array_get_buffer` shall return a non-NULL handle to the `buffer_index`-th const buffer in the array. **]**
211
212 **SRS_CONSTBUFFER_ARRAY_01_006: [** The returned handle shall have its reference count incremented. **]**
213
214 **SRS_CONSTBUFFER_ARRAY_01_007: [** If `constbuffer_array_handle` is NULL, `constbuffer_array_get_buffer` shall fail and return NULL. **]**
215
216 **SRS_CONSTBUFFER_ARRAY_01_008: [** If `buffer_index` is greater or equal to the number of buffers in the array, `constbuffer_array_get_buffer` shall fail and return NULL. **]**
217
218 ### constbuffer_array_get_buffer_content
219
220 ```c
221 MOCKABLE_FUNCTION(, const CONSTBUFFER*, constbuffer_array_get_buffer_content, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t, buffer_index);
222 ```
223
224 `constbuffer_array_get_buffer_content` gets the buffer content for the buffer at the `buffer_index`-th given index in the array.
225
226 **SRS_CONSTBUFFER_ARRAY_01_023: [** If `constbuffer_array_handle` is NULL, `constbuffer_array_get_buffer_content` shall fail and return NULL. **]**
227
228 **SRS_CONSTBUFFER_ARRAY_01_024: [** If `buffer_index` is greater or equal to the number of buffers in the array, `constbuffer_array_get_buffer_content` shall fail and return NULL. **]**
229
230 **SRS_CONSTBUFFER_ARRAY_01_025: [** Otherwise `constbuffer_array_get_buffer_content` shall call `CONSTBUFFER_GetContent` for the `buffer_index`-th buffer and return its result. **]**
231
232 ### constbuffer_array_get_all_buffers_size
233
234 ```c
235 MOCKABLE_FUNCTION(, int, constbuffer_array_get_all_buffers_size, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle, uint32_t*, all_buffers_size);
236 ```
237
238 `constbuffer_array_get_all_buffers_size` gets the size for all buffers (how much memory is held by all buffers in the array).
239
240 **SRS_CONSTBUFFER_ARRAY_01_019: [** If `constbuffer_array_handle` is NULL, `constbuffer_array_get_all_buffers_size` shall fail and return a non-zero value. **]**
241
242 **SRS_CONSTBUFFER_ARRAY_01_020: [** If `all_buffers_size` is NULL, `constbuffer_array_get_all_buffers_size` shall fail and return a non-zero value. **]**
243
244 **SRS_CONSTBUFFER_ARRAY_01_021: [** If summing up the sizes results in an `uint32_t` overflow, shall fail and return a non-zero value. **]**
245
246 **SRS_CONSTBUFFER_ARRAY_01_022: [** Otherwise `constbuffer_array_get_all_buffers_size` shall write in `all_buffers_size` the total size of all buffers in the array and return 0. **]**
247
248 ### constbuffer_array_get_const_buffer_handle_array
249
250 ```c
251 MOCKABLE_FUNCTION(, const CONSTBUFFER_HANDLE*, constbuffer_array_get_const_buffer_handle_array, CONSTBUFFER_ARRAY_HANDLE, constbuffer_array_handle);
252 ```
253
254 `constbuffer_array_get_const_buffer_handle_array` gets a const array with the handles for all the const buffers in the array.
255
256 **SRS_CONSTBUFFER_ARRAY_01_026: [** If `constbuffer_array_handle` is NULL, `constbuffer_array_get_const_buffer_handle_array` shall fail and return NULL. **]**
257
258 **SRS_CONSTBUFFER_ARRAY_01_027: [** Otherwise `constbuffer_array_get_const_buffer_handle_array` shall return the array of const buffer handles backing the const buffer array. **]**
259
260 ### CONSTBUFFER_ARRAY_HANDLE_contain_same
261 ```c
262 MOCKABLE_FUNCTION(, bool, CONSTBUFFER_ARRAY_HANDLE_contain_same, CONSTBUFFER_ARRAY_HANDLE, left, CONSTBUFFER_ARRAY_HANDLE, right);
263 ```
264
265 `CONSTBUFFER_ARRAY_HANDLE_contain_same` returns `true` if `left` and `right` have the some content.
266
267 **SRS_CONSTBUFFER_ARRAY_02_050: [** If `left` is `NULL` and `right` is `NULL` then `CONSTBUFFER_ARRAY_HANDLE_contain_same` shall return `true`. **]**
268
269 **SRS_CONSTBUFFER_ARRAY_02_051: [** If `left` is `NULL` and `right` is not `NULL` then `CONSTBUFFER_ARRAY_HANDLE_contain_same` shall return `false`. **]**
270
271 **SRS_CONSTBUFFER_ARRAY_02_052: [** If `left` is not `NULL` and `right` is `NULL` then `CONSTBUFFER_ARRAY_HANDLE_contain_same` shall return `false`. **]**
272
273 **SRS_CONSTBUFFER_ARRAY_02_053: [** If the number of `CONSTBUFFER_HANDLE`s in `left` is different then the number of `CONSTBUFFER_HANDLE`s in `right` then `CONSTBUFFER_ARRAY_HANDLE_contain_same` shall return `false`. **]**
274
275 **SRS_CONSTBUFFER_ARRAY_02_054: [** If `left` and `right` `CONSTBUFFER_HANDLE`s at same index are different (as indicated by `CONSTBUFFER_HANDLE_contain_same` call) then `CONSTBUFFER_ARRAY_HANDLE_contain_same` shall return `false`. **]**
276
277 **SRS_CONSTBUFFER_ARRAY_02_055: [** `CONSTBUFFER_ARRAY_HANDLE_contain_same` shall return `true`. **]**
278