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 */
35struct 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 */
48struct 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 */
77typedef bool(aws_byte_predicate_fn)(uint8_t value);
78
79AWS_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 */
86AWS_COMMON_API
87bool 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 */
96AWS_COMMON_API
97bool 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 */
109AWS_COMMON_API
110bool 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 */
120AWS_COMMON_API
121bool aws_array_eq_c_str_ignore_case(const void *const array, const size_t array_len, const char *const c_str);
122
123AWS_COMMON_API
124int 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 */
132AWS_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 */
141AWS_COMMON_API
142bool 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 */
148AWS_COMMON_API
149bool 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 */
159AWS_COMMON_API
160int 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
165AWS_COMMON_API
166void 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 */
172AWS_COMMON_API
173void 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 */
179AWS_COMMON_API
180void 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 */
185AWS_COMMON_API
186void 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 */
192AWS_COMMON_API
193bool 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 */
201AWS_COMMON_API
202bool 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 */
209AWS_COMMON_API
210bool 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 */
219AWS_COMMON_API
220bool 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 */
235AWS_COMMON_API
236bool 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 */
261AWS_COMMON_API
262int 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 */
287AWS_COMMON_API
288int 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 */
300AWS_COMMON_API
301int 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 */
310AWS_COMMON_API
311struct 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 */
318AWS_COMMON_API
319struct 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 */
326AWS_COMMON_API
327struct 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 */
334AWS_COMMON_API
335bool 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 */
343AWS_COMMON_API
344int 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 */
354AWS_COMMON_API
355int 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 */
368AWS_COMMON_API
369int 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 */
377AWS_COMMON_API
378int 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 */
386AWS_COMMON_API
387int 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 */
396AWS_COMMON_API
397int 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 */
405AWS_COMMON_API
406int 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 */
412AWS_COMMON_API
413bool 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 */
421AWS_COMMON_API
422bool 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 */
428AWS_COMMON_API
429bool 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 */
437AWS_COMMON_API
438bool 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 */
445AWS_COMMON_API
446bool 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 */
455AWS_COMMON_API
456bool 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 */
461AWS_COMMON_API
462uint64_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 */
468AWS_COMMON_API
469uint64_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 */
476AWS_COMMON_API
477const uint8_t *aws_lookup_table_to_lower_get(void);
478
479/**
480 * Lexical (byte value) comparison of two byte cursors
481 */
482AWS_COMMON_API
483int 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 */
488AWS_COMMON_API
489int 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 */
497AWS_COMMON_API struct aws_byte_buf aws_byte_buf_from_c_str(const char *c_str);
498
499AWS_COMMON_API struct aws_byte_buf aws_byte_buf_from_array(const void *bytes, size_t len);
500
501AWS_COMMON_API struct aws_byte_buf aws_byte_buf_from_empty_array(const void *bytes, size_t capacity);
502
503AWS_COMMON_API struct aws_byte_cursor aws_byte_cursor_from_buf(const struct aws_byte_buf *const buf);
504
505AWS_COMMON_API struct aws_byte_cursor aws_byte_cursor_from_c_str(const char *c_str);
506
507AWS_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 */
519AWS_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
531AWS_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 */
541AWS_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 */
553AWS_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 */
564AWS_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 */
574AWS_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 */
584AWS_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 */
594AWS_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 */
604AWS_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 */
614AWS_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 */
627AWS_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 */
639AWS_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 */
651AWS_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 */
662AWS_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 */
675AWS_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 */
684AWS_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 */
693AWS_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 */
702AWS_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 */
711AWS_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 */
720AWS_COMMON_API bool aws_byte_buf_write_float_be64(struct aws_byte_buf *buf, double x);
721
722AWS_EXTERN_C_END
723
724#endif /* AWS_COMMON_BYTE_BUF_H */
725