1 /* 2 * Copyright (c) 2014-2020 Pavel Kalvoda <me@pavelkalvoda.com> 3 * 4 * libcbor is free software; you can redistribute it and/or modify 5 * it under the terms of the MIT license. See LICENSE for details. 6 */ 7 8 #ifndef LIBCBOR_BYTESTRINGS_H 9 #define LIBCBOR_BYTESTRINGS_H 10 11 #include "cbor/cbor_export.h" 12 #include "cbor/common.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /* 19 * ============================================================================ 20 * Byte string manipulation 21 * ============================================================================ 22 */ 23 24 /** Returns the length of the binary data 25 * 26 * For definite byte strings only 27 * 28 * @param item a definite bytestring 29 * @return length of the binary data. Zero if no chunk has been attached yet 30 */ 31 _CBOR_NODISCARD 32 CBOR_EXPORT size_t cbor_bytestring_length(const cbor_item_t *item); 33 34 /** Is the byte string definite? 35 * 36 * @param item a byte string 37 * @return Is the byte string definite? 38 */ 39 _CBOR_NODISCARD 40 CBOR_EXPORT bool cbor_bytestring_is_definite(const cbor_item_t *item); 41 42 /** Is the byte string indefinite? 43 * 44 * @param item a byte string 45 * @return Is the byte string indefinite? 46 */ 47 _CBOR_NODISCARD 48 CBOR_EXPORT bool cbor_bytestring_is_indefinite(const cbor_item_t *item); 49 50 /** Get the handle to the binary data 51 * 52 * Definite items only. Modifying the data is allowed. In that case, the caller 53 * takes responsibility for the effect on items this item might be a part of 54 * 55 * @param item A definite byte string 56 * @return The address of the underlying binary data 57 * @return `NULL` if no data have been assigned 58 * yet. 59 */ 60 _CBOR_NODISCARD 61 CBOR_EXPORT cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item); 62 63 /** Set the handle to the binary data 64 * 65 * @param item A definite byte string 66 * @param data The memory block. The caller gives up the ownership of the block. 67 * libcbor will deallocate it when appropriate using the `free` implementation 68 * configured using #cbor_set_allocs 69 * @param length Length of the data block 70 */ 71 CBOR_EXPORT void cbor_bytestring_set_handle( 72 cbor_item_t *item, cbor_mutable_data CBOR_RESTRICT_POINTER data, 73 size_t length); 74 75 /** Get the handle to the array of chunks 76 * 77 * Manipulations with the memory block (e.g. sorting it) are allowed, but the 78 * validity and the number of chunks must be retained. 79 * 80 * @param item A indefinite byte string 81 * @return array of #cbor_bytestring_chunk_count definite bytestrings 82 */ 83 _CBOR_NODISCARD 84 CBOR_EXPORT cbor_item_t **cbor_bytestring_chunks_handle( 85 const cbor_item_t *item); 86 87 /** Get the number of chunks this string consist of 88 * 89 * @param item A indefinite bytestring 90 * @return The chunk count. 0 for freshly created items. 91 */ 92 _CBOR_NODISCARD 93 CBOR_EXPORT size_t cbor_bytestring_chunk_count(const cbor_item_t *item); 94 95 /** Appends a chunk to the bytestring 96 * 97 * Indefinite byte strings only. 98 * 99 * May realloc the chunk storage. 100 * 101 * @param item An indefinite byte string 102 * @param chunk A definite byte string. Its reference count will be be increased 103 * by one. 104 * @return true on success, false on realloc failure. In that case, the refcount 105 * of `chunk` is not increased and the `item` is left intact. 106 */ 107 _CBOR_NODISCARD 108 CBOR_EXPORT bool cbor_bytestring_add_chunk(cbor_item_t *item, 109 cbor_item_t *chunk); 110 111 /** Creates a new definite byte string 112 * 113 * The handle is initialized to `NULL` and length to 0 114 * 115 * @return Reference to the new bytestring item. The item's reference count is 116 * initialized to one. 117 * @return `NULL` if memory allocation fails 118 */ 119 _CBOR_NODISCARD 120 CBOR_EXPORT cbor_item_t *cbor_new_definite_bytestring(void); 121 122 /** Creates a new indefinite byte string 123 * 124 * The chunks array is initialized to `NULL` and chunk count to 0 125 * 126 * @return Reference to the new bytestring item. The item's reference count is 127 * initialized to one. 128 * @return `NULL` if memory allocation fails 129 */ 130 _CBOR_NODISCARD 131 CBOR_EXPORT cbor_item_t *cbor_new_indefinite_bytestring(void); 132 133 /** Creates a new byte string and initializes it 134 * 135 * The `handle` will be copied to a newly allocated block 136 * 137 * @param handle Block of binary data 138 * @param length Length of `data` 139 * @return Reference to the new bytestring item. The item's reference count is 140 * initialized to one. 141 * @return `NULL` if memory allocation fails 142 */ 143 _CBOR_NODISCARD 144 CBOR_EXPORT cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length); 145 146 #ifdef __cplusplus 147 } 148 #endif 149 150 #endif // LIBCBOR_BYTESTRINGS_H 151