1 | #ifndef AWS_COMMON_BYTE_BUF_H |
2 | #define AWS_COMMON_BYTE_BUF_H |
3 | /* |
4 | * Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
5 | * |
6 | * Licensed under the Apache License, Version 2.0 (the "License"). |
7 | * You may not use this file except in compliance with the License. |
8 | * A copy of the License is located at |
9 | * |
10 | * http://aws.amazon.com/apache2.0 |
11 | * |
12 | * or in the "license" file accompanying this file. This file is distributed |
13 | * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either |
14 | * express or implied. See the License for the specific language governing |
15 | * permissions and limitations under the License. |
16 | */ |
17 | |
18 | #include <aws/common/array_list.h> |
19 | #include <aws/common/byte_order.h> |
20 | #include <aws/common/common.h> |
21 | |
22 | #include <string.h> |
23 | |
24 | /** |
25 | * Represents a length-delimited binary string or buffer. If byte buffer points |
26 | * to constant memory or memory that should otherwise not be freed by this |
27 | * struct, set allocator to NULL and free function will be a no-op. |
28 | * |
29 | * This structure used to define the output for all functions that write to a buffer. |
30 | * |
31 | * Note that this structure allocates memory at the buffer pointer only. The |
32 | * struct itself does not get dynamically allocated and must be either |
33 | * maintained or copied to avoid losing access to the memory. |
34 | */ |
35 | struct aws_byte_buf { |
36 | /* do not reorder this, this struct lines up nicely with windows buffer structures--saving us allocations.*/ |
37 | size_t len; |
38 | uint8_t *buffer; |
39 | size_t capacity; |
40 | struct aws_allocator *allocator; |
41 | }; |
42 | |
43 | /** |
44 | * Represents a movable pointer within a larger binary string or buffer. |
45 | * |
46 | * This structure is used to define buffers for reading. |
47 | */ |
48 | struct aws_byte_cursor { |
49 | /* do not reorder this, this struct lines up nicely with windows buffer structures--saving us allocations */ |
50 | size_t len; |
51 | uint8_t *ptr; |
52 | }; |
53 | |
54 | /** |
55 | * Helper macro for passing aws_byte_cursor to the printf family of functions. |
56 | * Intended for use with the PRInSTR format macro. |
57 | * Ex: printf(PRInSTR "\n", AWS_BYTE_CURSOR_PRI(my_cursor)); |
58 | */ |
59 | #define AWS_BYTE_CURSOR_PRI(C) ((int)(C).len < 0 ? 0 : (int)(C).len), (const char *)(C).ptr |
60 | |
61 | /** |
62 | * Helper macro for passing aws_byte_buf to the printf family of functions. |
63 | * Intended for use with the PRInSTR format macro. |
64 | * Ex: printf(PRInSTR "\n", AWS_BYTE_BUF_PRI(my_buf)); |
65 | */ |
66 | #define AWS_BYTE_BUF_PRI(B) ((int)(B).len < 0 ? 0 : (int)(B).len), (const char *)(B).buffer |
67 | |
68 | /** |
69 | * Helper Macro for inititilizing a byte cursor from a string literal |
70 | */ |
71 | #define AWS_BYTE_CUR_INIT_FROM_STRING_LITERAL(literal) \ |
72 | { .ptr = (uint8_t *)(const char *)(literal), .len = sizeof(literal) - 1 } |
73 | |
74 | /** |
75 | * Signature for function argument to trim APIs |
76 | */ |
77 | typedef bool(aws_byte_predicate_fn)(uint8_t value); |
78 | |
79 | AWS_EXTERN_C_BEGIN |
80 | |
81 | /** |
82 | * Compare two arrays. |
83 | * Return whether their contents are equivalent. |
84 | * NULL may be passed as the array pointer if its length is declared to be 0. |
85 | */ |
86 | AWS_COMMON_API |
87 | bool aws_array_eq(const void *const array_a, const size_t len_a, const void *array_b, const size_t len_b); |
88 | |
89 | /** |
90 | * Perform a case-insensitive string comparison of two arrays. |
91 | * Return whether their contents are equivalent. |
92 | * NULL may be passed as the array pointer if its length is declared to be 0. |
93 | * The "C" locale is used for comparing upper and lowercase letters. |
94 | * Data is assumed to be ASCII text, UTF-8 will work fine too. |
95 | */ |
96 | AWS_COMMON_API |
97 | bool aws_array_eq_ignore_case( |
98 | const void *const array_a, |
99 | const size_t len_a, |
100 | const void *const array_b, |
101 | const size_t len_b); |
102 | |
103 | /** |
104 | * Compare an array and a null-terminated string. |
105 | * Returns true if their contents are equivalent. |
106 | * The array should NOT contain a null-terminator, or the comparison will always return false. |
107 | * NULL may be passed as the array pointer if its length is declared to be 0. |
108 | */ |
109 | AWS_COMMON_API |
110 | bool aws_array_eq_c_str(const void *const array, const size_t array_len, const char *const c_str); |
111 | |
112 | /** |
113 | * Perform a case-insensitive string comparison of an array and a null-terminated string. |
114 | * Return whether their contents are equivalent. |
115 | * The array should NOT contain a null-terminator, or the comparison will always return false. |
116 | * NULL may be passed as the array pointer if its length is declared to be 0. |
117 | * The "C" locale is used for comparing upper and lowercase letters. |
118 | * Data is assumed to be ASCII text, UTF-8 will work fine too. |
119 | */ |
120 | AWS_COMMON_API |
121 | bool aws_array_eq_c_str_ignore_case(const void *const array, const size_t array_len, const char *const c_str); |
122 | |
123 | AWS_COMMON_API |
124 | int aws_byte_buf_init(struct aws_byte_buf *buf, struct aws_allocator *allocator, size_t capacity); |
125 | |
126 | /** |
127 | * Initializes an aws_byte_buf structure base on another valid one. |
128 | * Requires: *src and *allocator are valid objects. |
129 | * Ensures: *dest is a valid aws_byte_buf with a new backing array dest->buffer |
130 | * which is a copy of the elements from src->buffer. |
131 | */ |
132 | AWS_COMMON_API int aws_byte_buf_init_copy( |
133 | struct aws_byte_buf *dest, |
134 | struct aws_allocator *allocator, |
135 | const struct aws_byte_buf *src); |
136 | |
137 | /** |
138 | * Evaluates the set of properties that define the shape of all valid aws_byte_buf structures. |
139 | * It is also a cheap check, in the sense it run in constant time (i.e., no loops or recursion). |
140 | */ |
141 | AWS_COMMON_API |
142 | bool aws_byte_buf_is_valid(const struct aws_byte_buf *const buf); |
143 | |
144 | /** |
145 | * Evaluates the set of properties that define the shape of all valid aws_byte_cursor structures. |
146 | * It is also a cheap check, in the sense it runs in constant time (i.e., no loops or recursion). |
147 | */ |
148 | AWS_COMMON_API |
149 | bool aws_byte_cursor_is_valid(const struct aws_byte_cursor *cursor); |
150 | |
151 | /** |
152 | * Copies src buffer into dest and sets the correct len and capacity. |
153 | * A new memory zone is allocated for dest->buffer. When dest is no longer needed it will have to be cleaned-up using |
154 | * aws_byte_buf_clean_up(dest). |
155 | * Dest capacity and len will be equal to the src len. Allocator of the dest will be identical with parameter allocator. |
156 | * If src buffer is null the dest will have a null buffer with a len and a capacity of 0 |
157 | * Returns AWS_OP_SUCCESS in case of success or AWS_OP_ERR when memory can't be allocated. |
158 | */ |
159 | AWS_COMMON_API |
160 | int aws_byte_buf_init_copy_from_cursor( |
161 | struct aws_byte_buf *dest, |
162 | struct aws_allocator *allocator, |
163 | struct aws_byte_cursor src); |
164 | |
165 | AWS_COMMON_API |
166 | void aws_byte_buf_clean_up(struct aws_byte_buf *buf); |
167 | |
168 | /** |
169 | * Equivalent to calling aws_byte_buf_secure_zero and then aws_byte_buf_clean_up |
170 | * on the buffer. |
171 | */ |
172 | AWS_COMMON_API |
173 | void aws_byte_buf_clean_up_secure(struct aws_byte_buf *buf); |
174 | |
175 | /** |
176 | * Resets the len of the buffer to 0, but does not free the memory. The buffer can then be reused. |
177 | * Optionally zeroes the contents, if the "zero_contents" flag is true. |
178 | */ |
179 | AWS_COMMON_API |
180 | void aws_byte_buf_reset(struct aws_byte_buf *buf, bool zero_contents); |
181 | |
182 | /** |
183 | * Sets all bytes of buffer to zero and resets len to zero. |
184 | */ |
185 | AWS_COMMON_API |
186 | void aws_byte_buf_secure_zero(struct aws_byte_buf *buf); |
187 | |
188 | /** |
189 | * Compare two aws_byte_buf structures. |
190 | * Return whether their contents are equivalent. |
191 | */ |
192 | AWS_COMMON_API |
193 | bool aws_byte_buf_eq(const struct aws_byte_buf *const a, const struct aws_byte_buf *const b); |
194 | |
195 | /** |
196 | * Perform a case-insensitive string comparison of two aws_byte_buf structures. |
197 | * Return whether their contents are equivalent. |
198 | * The "C" locale is used for comparing upper and lowercase letters. |
199 | * Data is assumed to be ASCII text, UTF-8 will work fine too. |
200 | */ |
201 | AWS_COMMON_API |
202 | bool aws_byte_buf_eq_ignore_case(const struct aws_byte_buf *const a, const struct aws_byte_buf *const b); |
203 | |
204 | /** |
205 | * Compare an aws_byte_buf and a null-terminated string. |
206 | * Returns true if their contents are equivalent. |
207 | * The buffer should NOT contain a null-terminator, or the comparison will always return false. |
208 | */ |
209 | AWS_COMMON_API |
210 | bool aws_byte_buf_eq_c_str(const struct aws_byte_buf *const buf, const char *const c_str); |
211 | |
212 | /** |
213 | * Perform a case-insensitive string comparison of an aws_byte_buf and a null-terminated string. |
214 | * Return whether their contents are equivalent. |
215 | * The buffer should NOT contain a null-terminator, or the comparison will always return false. |
216 | * The "C" locale is used for comparing upper and lowercase letters. |
217 | * Data is assumed to be ASCII text, UTF-8 will work fine too. |
218 | */ |
219 | AWS_COMMON_API |
220 | bool aws_byte_buf_eq_c_str_ignore_case(const struct aws_byte_buf *const buf, const char *const c_str); |
221 | |
222 | /** |
223 | * No copies, no buffer allocations. Iterates over input_str, and returns the next substring between split_on instances. |
224 | * |
225 | * Edge case rules are as follows: |
226 | * If the input begins with split_on, an empty cursor will be the first entry returned. |
227 | * If the input has two adjacent split_on tokens, an empty cursor will be returned. |
228 | * If the input ends with split_on, an empty cursor will be returned last. |
229 | * |
230 | * It is the user's responsibility to properly zero-initialize substr. |
231 | * |
232 | * It is the user's responsibility to make sure the input buffer stays in memory |
233 | * long enough to use the results. |
234 | */ |
235 | AWS_COMMON_API |
236 | bool aws_byte_cursor_next_split( |
237 | const struct aws_byte_cursor *AWS_RESTRICT input_str, |
238 | char split_on, |
239 | struct aws_byte_cursor *AWS_RESTRICT substr); |
240 | |
241 | /** |
242 | * No copies, no buffer allocations. Fills in output with a list of |
243 | * aws_byte_cursor instances where buffer is an offset into the input_str and |
244 | * len is the length of that string in the original buffer. |
245 | * |
246 | * Edge case rules are as follows: |
247 | * if the input begins with split_on, an empty cursor will be the first entry in |
248 | * output. if the input has two adjacent split_on tokens, an empty cursor will |
249 | * be inserted into the output. if the input ends with split_on, an empty cursor |
250 | * will be appended to the output. |
251 | * |
252 | * It is the user's responsibility to properly initialize output. Recommended number of preallocated elements from |
253 | * output is your most likely guess for the upper bound of the number of elements resulting from the split. |
254 | * |
255 | * The type that will be stored in output is struct aws_byte_cursor (you'll need |
256 | * this for the item size param). |
257 | * |
258 | * It is the user's responsibility to make sure the input buffer stays in memory |
259 | * long enough to use the results. |
260 | */ |
261 | AWS_COMMON_API |
262 | int aws_byte_cursor_split_on_char( |
263 | const struct aws_byte_cursor *AWS_RESTRICT input_str, |
264 | char split_on, |
265 | struct aws_array_list *AWS_RESTRICT output); |
266 | |
267 | /** |
268 | * No copies, no buffer allocations. Fills in output with a list of aws_byte_cursor instances where buffer is |
269 | * an offset into the input_str and len is the length of that string in the original buffer. N is the max number of |
270 | * splits, if this value is zero, it will add all splits to the output. |
271 | * |
272 | * Edge case rules are as follows: |
273 | * if the input begins with split_on, an empty cursor will be the first entry in output |
274 | * if the input has two adjacent split_on tokens, an empty cursor will be inserted into the output. |
275 | * if the input ends with split_on, an empty cursor will be appended to the output. |
276 | * |
277 | * It is the user's responsibility to properly initialize output. Recommended number of preallocated elements from |
278 | * output is your most likely guess for the upper bound of the number of elements resulting from the split. |
279 | * |
280 | * If the output array is not large enough, input_str will be updated to point to the first character after the last |
281 | * processed split_on instance. |
282 | * |
283 | * The type that will be stored in output is struct aws_byte_cursor (you'll need this for the item size param). |
284 | * |
285 | * It is the user's responsibility to make sure the input buffer stays in memory long enough to use the results. |
286 | */ |
287 | AWS_COMMON_API |
288 | int aws_byte_cursor_split_on_char_n( |
289 | const struct aws_byte_cursor *AWS_RESTRICT input_str, |
290 | char split_on, |
291 | size_t n, |
292 | struct aws_array_list *AWS_RESTRICT output); |
293 | |
294 | /** |
295 | * Search for an exact byte match inside a cursor. The first match will be returned. Returns AWS_OP_SUCCESS |
296 | * on successful match and first_find will be set to the offset in input_str, and length will be the remaining length |
297 | * from input_str past the returned offset. If the match was not found, AWS_OP_ERR will be returned and |
298 | * AWS_ERROR_STRING_MATCH_NOT_FOUND will be raised. |
299 | */ |
300 | AWS_COMMON_API |
301 | int aws_byte_cursor_find_exact( |
302 | const struct aws_byte_cursor *AWS_RESTRICT input_str, |
303 | const struct aws_byte_cursor *AWS_RESTRICT to_find, |
304 | struct aws_byte_cursor *first_find); |
305 | |
306 | /** |
307 | * |
308 | * Shrinks a byte cursor from the right for as long as the supplied predicate is true |
309 | */ |
310 | AWS_COMMON_API |
311 | struct aws_byte_cursor aws_byte_cursor_right_trim_pred( |
312 | const struct aws_byte_cursor *source, |
313 | aws_byte_predicate_fn *predicate); |
314 | |
315 | /** |
316 | * Shrinks a byte cursor from the left for as long as the supplied predicate is true |
317 | */ |
318 | AWS_COMMON_API |
319 | struct aws_byte_cursor aws_byte_cursor_left_trim_pred( |
320 | const struct aws_byte_cursor *source, |
321 | aws_byte_predicate_fn *predicate); |
322 | |
323 | /** |
324 | * Shrinks a byte cursor from both sides for as long as the supplied predicate is true |
325 | */ |
326 | AWS_COMMON_API |
327 | struct aws_byte_cursor aws_byte_cursor_trim_pred( |
328 | const struct aws_byte_cursor *source, |
329 | aws_byte_predicate_fn *predicate); |
330 | |
331 | /** |
332 | * Returns true if the byte cursor's range of bytes all satisfy the predicate |
333 | */ |
334 | AWS_COMMON_API |
335 | bool aws_byte_cursor_satisfies_pred(const struct aws_byte_cursor *source, aws_byte_predicate_fn *predicate); |
336 | |
337 | /** |
338 | * Copies from to to. If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be |
339 | * returned. dest->len will contain the amount of data actually copied to dest. |
340 | * |
341 | * from and to may be the same buffer, permitting copying a buffer into itself. |
342 | */ |
343 | AWS_COMMON_API |
344 | int aws_byte_buf_append(struct aws_byte_buf *to, const struct aws_byte_cursor *from); |
345 | |
346 | /** |
347 | * Copies from to to while converting bytes via the passed in lookup table. |
348 | * If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be |
349 | * returned. to->len will contain its original size plus the amount of data actually copied to to. |
350 | * |
351 | * from and to should not be the same buffer (overlap is not handled) |
352 | * lookup_table must be at least 256 bytes |
353 | */ |
354 | AWS_COMMON_API |
355 | int aws_byte_buf_append_with_lookup( |
356 | struct aws_byte_buf *AWS_RESTRICT to, |
357 | const struct aws_byte_cursor *AWS_RESTRICT from, |
358 | const uint8_t *lookup_table); |
359 | |
360 | /** |
361 | * Copies from to to. If to is too small, the buffer will be grown appropriately and |
362 | * the old contents copied to, before the new contents are appended. |
363 | * |
364 | * If the grow fails (overflow or OOM), then an error will be returned. |
365 | * |
366 | * from and to may be the same buffer, permitting copying a buffer into itself. |
367 | */ |
368 | AWS_COMMON_API |
369 | int aws_byte_buf_append_dynamic(struct aws_byte_buf *to, const struct aws_byte_cursor *from); |
370 | |
371 | /** |
372 | * Copy contents of cursor to buffer, then update cursor to reference the memory stored in the buffer. |
373 | * If buffer is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be returned. |
374 | * |
375 | * The cursor is permitted to reference memory from earlier in the buffer. |
376 | */ |
377 | AWS_COMMON_API |
378 | int aws_byte_buf_append_and_update(struct aws_byte_buf *to, struct aws_byte_cursor *from_and_update); |
379 | |
380 | /** |
381 | * Attempts to increase the capacity of a buffer to the requested capacity |
382 | * |
383 | * If the the buffer's capacity is currently larger than the request capacity, the |
384 | * function does nothing (no shrink is performed). |
385 | */ |
386 | AWS_COMMON_API |
387 | int aws_byte_buf_reserve(struct aws_byte_buf *buffer, size_t requested_capacity); |
388 | |
389 | /** |
390 | * Convenience function that attempts to increase the capacity of a buffer relative to the current |
391 | * length. |
392 | * |
393 | * aws_byte_buf_reserve_relative(buf, x) ~~ aws_byte_buf_reserve(buf, buf->len + x) |
394 | * |
395 | */ |
396 | AWS_COMMON_API |
397 | int aws_byte_buf_reserve_relative(struct aws_byte_buf *buffer, size_t additional_length); |
398 | |
399 | /** |
400 | * Concatenates a variable number of struct aws_byte_buf * into destination. |
401 | * Number of args must be greater than 1. If dest is too small, |
402 | * AWS_ERROR_DEST_COPY_TOO_SMALL will be returned. dest->len will contain the |
403 | * amount of data actually copied to dest. |
404 | */ |
405 | AWS_COMMON_API |
406 | int aws_byte_buf_cat(struct aws_byte_buf *dest, size_t number_of_args, ...); |
407 | |
408 | /** |
409 | * Compare two aws_byte_cursor structures. |
410 | * Return whether their contents are equivalent. |
411 | */ |
412 | AWS_COMMON_API |
413 | bool aws_byte_cursor_eq(const struct aws_byte_cursor *a, const struct aws_byte_cursor *b); |
414 | |
415 | /** |
416 | * Perform a case-insensitive string comparison of two aws_byte_cursor structures. |
417 | * Return whether their contents are equivalent. |
418 | * The "C" locale is used for comparing upper and lowercase letters. |
419 | * Data is assumed to be ASCII text, UTF-8 will work fine too. |
420 | */ |
421 | AWS_COMMON_API |
422 | bool aws_byte_cursor_eq_ignore_case(const struct aws_byte_cursor *a, const struct aws_byte_cursor *b); |
423 | |
424 | /** |
425 | * Compare an aws_byte_cursor and an aws_byte_buf. |
426 | * Return whether their contents are equivalent. |
427 | */ |
428 | AWS_COMMON_API |
429 | bool aws_byte_cursor_eq_byte_buf(const struct aws_byte_cursor *const a, const struct aws_byte_buf *const b); |
430 | |
431 | /** |
432 | * Perform a case-insensitive string comparison of an aws_byte_cursor and an aws_byte_buf. |
433 | * Return whether their contents are equivalent. |
434 | * The "C" locale is used for comparing upper and lowercase letters. |
435 | * Data is assumed to be ASCII text, UTF-8 will work fine too. |
436 | */ |
437 | AWS_COMMON_API |
438 | bool aws_byte_cursor_eq_byte_buf_ignore_case(const struct aws_byte_cursor *const a, const struct aws_byte_buf *const b); |
439 | |
440 | /** |
441 | * Compare an aws_byte_cursor and a null-terminated string. |
442 | * Returns true if their contents are equivalent. |
443 | * The cursor should NOT contain a null-terminator, or the comparison will always return false. |
444 | */ |
445 | AWS_COMMON_API |
446 | bool aws_byte_cursor_eq_c_str(const struct aws_byte_cursor *const cursor, const char *const c_str); |
447 | |
448 | /** |
449 | * Perform a case-insensitive string comparison of an aws_byte_cursor and a null-terminated string. |
450 | * Return whether their contents are equivalent. |
451 | * The cursor should NOT contain a null-terminator, or the comparison will always return false. |
452 | * The "C" locale is used for comparing upper and lowercase letters. |
453 | * Data is assumed to be ASCII text, UTF-8 will work fine too. |
454 | */ |
455 | AWS_COMMON_API |
456 | bool aws_byte_cursor_eq_c_str_ignore_case(const struct aws_byte_cursor *const cursor, const char *const c_str); |
457 | |
458 | /** |
459 | * Case-insensitive hash function for array containing ASCII or UTF-8 text. |
460 | */ |
461 | AWS_COMMON_API |
462 | uint64_t aws_hash_array_ignore_case(const void *array, const size_t len); |
463 | |
464 | /** |
465 | * Case-insensitive hash function for aws_byte_cursors stored in an aws_hash_table. |
466 | * For case-sensitive hashing, use aws_hash_byte_cursor_ptr(). |
467 | */ |
468 | AWS_COMMON_API |
469 | uint64_t aws_hash_byte_cursor_ptr_ignore_case(const void *item); |
470 | |
471 | /** |
472 | * Returns a lookup table for bytes that is the identity transformation with the exception |
473 | * of uppercase ascii characters getting replaced with lowercase characters. Used in |
474 | * caseless comparisons. |
475 | */ |
476 | AWS_COMMON_API |
477 | const uint8_t *aws_lookup_table_to_lower_get(void); |
478 | |
479 | /** |
480 | * Lexical (byte value) comparison of two byte cursors |
481 | */ |
482 | AWS_COMMON_API |
483 | int aws_byte_cursor_compare_lexical(const struct aws_byte_cursor *lhs, const struct aws_byte_cursor *rhs); |
484 | |
485 | /** |
486 | * Lexical (byte value) comparison of two byte cursors where the raw values are sent through a lookup table first |
487 | */ |
488 | AWS_COMMON_API |
489 | int aws_byte_cursor_compare_lookup( |
490 | const struct aws_byte_cursor *lhs, |
491 | const struct aws_byte_cursor *rhs, |
492 | const uint8_t *lookup_table); |
493 | |
494 | /** |
495 | * For creating a byte buffer from a null-terminated string literal. |
496 | */ |
497 | AWS_COMMON_API struct aws_byte_buf aws_byte_buf_from_c_str(const char *c_str); |
498 | |
499 | AWS_COMMON_API struct aws_byte_buf aws_byte_buf_from_array(const void *bytes, size_t len); |
500 | |
501 | AWS_COMMON_API struct aws_byte_buf aws_byte_buf_from_empty_array(const void *bytes, size_t capacity); |
502 | |
503 | AWS_COMMON_API struct aws_byte_cursor aws_byte_cursor_from_buf(const struct aws_byte_buf *const buf); |
504 | |
505 | AWS_COMMON_API struct aws_byte_cursor aws_byte_cursor_from_c_str(const char *c_str); |
506 | |
507 | AWS_COMMON_API struct aws_byte_cursor aws_byte_cursor_from_array(const void *const bytes, const size_t len); |
508 | |
509 | /** |
510 | * Tests if the given aws_byte_cursor has at least len bytes remaining. If so, |
511 | * *buf is advanced by len bytes (incrementing ->ptr and decrementing ->len), |
512 | * and an aws_byte_cursor referring to the first len bytes of the original *buf |
513 | * is returned. Otherwise, an aws_byte_cursor with ->ptr = NULL, ->len = 0 is |
514 | * returned. |
515 | * |
516 | * Note that if len is above (SIZE_MAX / 2), this function will also treat it as |
517 | * a buffer overflow, and return NULL without changing *buf. |
518 | */ |
519 | AWS_COMMON_API struct aws_byte_cursor aws_byte_cursor_advance(struct aws_byte_cursor *const cursor, const size_t len); |
520 | |
521 | /** |
522 | * Behaves identically to aws_byte_cursor_advance, but avoids speculative |
523 | * execution potentially reading out-of-bounds pointers (by returning an |
524 | * empty ptr in such speculated paths). |
525 | * |
526 | * This should generally be done when using an untrusted or |
527 | * data-dependent value for 'len', to avoid speculating into a path where |
528 | * cursor->ptr points outside the true ptr length. |
529 | */ |
530 | |
531 | AWS_COMMON_API struct aws_byte_cursor aws_byte_cursor_advance_nospec(struct aws_byte_cursor *const cursor, size_t len); |
532 | |
533 | /** |
534 | * Reads specified length of data from byte cursor and copies it to the |
535 | * destination array. |
536 | * |
537 | * On success, returns true and updates the cursor pointer/length accordingly. |
538 | * If there is insufficient space in the cursor, returns false, leaving the |
539 | * cursor unchanged. |
540 | */ |
541 | AWS_COMMON_API bool aws_byte_cursor_read( |
542 | struct aws_byte_cursor *AWS_RESTRICT cur, |
543 | void *AWS_RESTRICT dest, |
544 | const size_t len); |
545 | |
546 | /** |
547 | * Reads as many bytes from cursor as size of buffer, and copies them to buffer. |
548 | * |
549 | * On success, returns true and updates the cursor pointer/length accordingly. |
550 | * If there is insufficient space in the cursor, returns false, leaving the |
551 | * cursor unchanged. |
552 | */ |
553 | AWS_COMMON_API bool aws_byte_cursor_read_and_fill_buffer( |
554 | struct aws_byte_cursor *AWS_RESTRICT cur, |
555 | struct aws_byte_buf *AWS_RESTRICT dest); |
556 | |
557 | /** |
558 | * Reads a single byte from cursor, placing it in *var. |
559 | * |
560 | * On success, returns true and updates the cursor pointer/length accordingly. |
561 | * If there is insufficient space in the cursor, returns false, leaving the |
562 | * cursor unchanged. |
563 | */ |
564 | AWS_COMMON_API bool aws_byte_cursor_read_u8(struct aws_byte_cursor *AWS_RESTRICT cur, uint8_t *AWS_RESTRICT var); |
565 | |
566 | /** |
567 | * Reads a 16-bit value in network byte order from cur, and places it in host |
568 | * byte order into var. |
569 | * |
570 | * On success, returns true and updates the cursor pointer/length accordingly. |
571 | * If there is insufficient space in the cursor, returns false, leaving the |
572 | * cursor unchanged. |
573 | */ |
574 | AWS_COMMON_API bool aws_byte_cursor_read_be16(struct aws_byte_cursor *cur, uint16_t *var); |
575 | |
576 | /** |
577 | * Reads a 32-bit value in network byte order from cur, and places it in host |
578 | * byte order into var. |
579 | * |
580 | * On success, returns true and updates the cursor pointer/length accordingly. |
581 | * If there is insufficient space in the cursor, returns false, leaving the |
582 | * cursor unchanged. |
583 | */ |
584 | AWS_COMMON_API bool aws_byte_cursor_read_be32(struct aws_byte_cursor *cur, uint32_t *var); |
585 | |
586 | /** |
587 | * Reads a 32-bit value in network byte order from cur, and places it in host |
588 | * byte order into var. |
589 | * |
590 | * On success, returns true and updates the cursor pointer/length accordingly. |
591 | * If there is insufficient space in the cursor, returns false, leaving the |
592 | * cursor unchanged. |
593 | */ |
594 | AWS_COMMON_API bool aws_byte_cursor_read_float_be32(struct aws_byte_cursor *cur, float *var); |
595 | |
596 | /** |
597 | * Reads a 64-bit value in network byte order from cur, and places it in host |
598 | * byte order into var. |
599 | * |
600 | * On success, returns true and updates the cursor pointer/length accordingly. |
601 | * If there is insufficient space in the cursor, returns false, leaving the |
602 | * cursor unchanged. |
603 | */ |
604 | AWS_COMMON_API bool aws_byte_cursor_read_float_be64(struct aws_byte_cursor *cur, double *var); |
605 | |
606 | /** |
607 | * Reads a 64-bit value in network byte order from cur, and places it in host |
608 | * byte order into var. |
609 | * |
610 | * On success, returns true and updates the cursor pointer/length accordingly. |
611 | * If there is insufficient space in the cursor, returns false, leaving the |
612 | * cursor unchanged. |
613 | */ |
614 | AWS_COMMON_API bool aws_byte_cursor_read_be64(struct aws_byte_cursor *cur, uint64_t *var); |
615 | |
616 | /** |
617 | * Appends a sub-buffer to the specified buffer. |
618 | * |
619 | * If the buffer has at least `len' bytes remaining (buffer->capacity - buffer->len >= len), |
620 | * then buffer->len is incremented by len, and an aws_byte_buf is assigned to *output corresponding |
621 | * to the last len bytes of the input buffer. The aws_byte_buf at *output will have a null |
622 | * allocator, a zero initial length, and a capacity of 'len'. The function then returns true. |
623 | * |
624 | * If there is insufficient space, then this function nulls all fields in *output and returns |
625 | * false. |
626 | */ |
627 | AWS_COMMON_API bool aws_byte_buf_advance( |
628 | struct aws_byte_buf *const AWS_RESTRICT buffer, |
629 | struct aws_byte_buf *const AWS_RESTRICT output, |
630 | const size_t len); |
631 | |
632 | /** |
633 | * Write specified number of bytes from array to byte buffer. |
634 | * |
635 | * On success, returns true and updates the buffer length accordingly. |
636 | * If there is insufficient space in the buffer, returns false, leaving the |
637 | * buffer unchanged. |
638 | */ |
639 | AWS_COMMON_API bool aws_byte_buf_write( |
640 | struct aws_byte_buf *AWS_RESTRICT buf, |
641 | const uint8_t *AWS_RESTRICT src, |
642 | size_t len); |
643 | |
644 | /** |
645 | * Copies all bytes from buffer to buffer. |
646 | * |
647 | * On success, returns true and updates the buffer /length accordingly. |
648 | * If there is insufficient space in the buffer, returns false, leaving the |
649 | * buffer unchanged. |
650 | */ |
651 | AWS_COMMON_API bool aws_byte_buf_write_from_whole_buffer( |
652 | struct aws_byte_buf *AWS_RESTRICT buf, |
653 | struct aws_byte_buf src); |
654 | |
655 | /** |
656 | * Copies all bytes from buffer to buffer. |
657 | * |
658 | * On success, returns true and updates the buffer /length accordingly. |
659 | * If there is insufficient space in the buffer, returns false, leaving the |
660 | * buffer unchanged. |
661 | */ |
662 | AWS_COMMON_API bool aws_byte_buf_write_from_whole_cursor( |
663 | struct aws_byte_buf *AWS_RESTRICT buf, |
664 | struct aws_byte_cursor src); |
665 | |
666 | /** |
667 | * Copies one byte to buffer. |
668 | * |
669 | * On success, returns true and updates the cursor /length |
670 | accordingly. |
671 | |
672 | * If there is insufficient space in the cursor, returns false, leaving the |
673 | cursor unchanged. |
674 | */ |
675 | AWS_COMMON_API bool aws_byte_buf_write_u8(struct aws_byte_buf *AWS_RESTRICT buf, uint8_t c); |
676 | |
677 | /** |
678 | * Writes a 16-bit integer in network byte order (big endian) to buffer. |
679 | * |
680 | * On success, returns true and updates the cursor /length accordingly. |
681 | * If there is insufficient space in the cursor, returns false, leaving the |
682 | * cursor unchanged. |
683 | */ |
684 | AWS_COMMON_API bool aws_byte_buf_write_be16(struct aws_byte_buf *buf, uint16_t x); |
685 | |
686 | /** |
687 | * Writes a 32-bit integer in network byte order (big endian) to buffer. |
688 | * |
689 | * On success, returns true and updates the cursor /length accordingly. |
690 | * If there is insufficient space in the cursor, returns false, leaving the |
691 | * cursor unchanged. |
692 | */ |
693 | AWS_COMMON_API bool aws_byte_buf_write_be32(struct aws_byte_buf *buf, uint32_t x); |
694 | |
695 | /** |
696 | * Writes a 32-bit float in network byte order (big endian) to buffer. |
697 | * |
698 | * On success, returns true and updates the cursor /length accordingly. |
699 | * If there is insufficient space in the cursor, returns false, leaving the |
700 | * cursor unchanged. |
701 | */ |
702 | AWS_COMMON_API bool aws_byte_buf_write_float_be32(struct aws_byte_buf *buf, float x); |
703 | |
704 | /** |
705 | * Writes a 64-bit integer in network byte order (big endian) to buffer. |
706 | * |
707 | * On success, returns true and updates the cursor /length accordingly. |
708 | * If there is insufficient space in the cursor, returns false, leaving the |
709 | * cursor unchanged. |
710 | */ |
711 | AWS_COMMON_API bool aws_byte_buf_write_be64(struct aws_byte_buf *buf, uint64_t x); |
712 | |
713 | /** |
714 | * Writes a 64-bit float in network byte order (big endian) to buffer. |
715 | * |
716 | * On success, returns true and updates the cursor /length accordingly. |
717 | * If there is insufficient space in the cursor, returns false, leaving the |
718 | * cursor unchanged. |
719 | */ |
720 | AWS_COMMON_API bool aws_byte_buf_write_float_be64(struct aws_byte_buf *buf, double x); |
721 | |
722 | AWS_EXTERN_C_END |
723 | |
724 | #endif /* AWS_COMMON_BYTE_BUF_H */ |
725 | |