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[borrow] a definite bytestring 29 * @return length of the binary data. Zero if no chunk has been attached yet 30 */ 31 CBOR_EXPORT size_t cbor_bytestring_length(const cbor_item_t *item); 32 33 /** Is the byte string definite? 34 * 35 * @param item[borrow] a byte string 36 * @return Is the byte string definite? 37 */ 38 CBOR_EXPORT bool cbor_bytestring_is_definite(const cbor_item_t *item); 39 40 /** Is the byte string indefinite? 41 * 42 * @param item[borrow] a byte string 43 * @return Is the byte string indefinite? 44 */ 45 CBOR_EXPORT bool cbor_bytestring_is_indefinite(const cbor_item_t *item); 46 47 /** Get the handle to the binary data 48 * 49 * Definite items only. Modifying the data is allowed. In that case, the caller 50 * takes responsibility for the effect on items this item might be a part of 51 * 52 * @param item[borrow] A definite byte string 53 * @return The address of the binary data. `NULL` if no data have been assigned 54 * yet. 55 */ 56 CBOR_EXPORT cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item); 57 58 /** Set the handle to the binary data 59 * 60 * @param item[borrow] A definite byte string 61 * @param data The memory block. The caller gives up the ownership of the block. 62 * libcbor will deallocate it when appropriate using its free function 63 * @param length Length of the data block 64 */ 65 CBOR_EXPORT void cbor_bytestring_set_handle( 66 cbor_item_t *item, cbor_mutable_data CBOR_RESTRICT_POINTER data, 67 size_t length); 68 69 /** Get the handle to the array of chunks 70 * 71 * Manipulations with the memory block (e.g. sorting it) are allowed, but the 72 * validity and the number of chunks must be retained. 73 * 74 * @param item[borrow] A indefinite byte string 75 * @return array of #cbor_bytestring_chunk_count definite bytestrings 76 */ 77 CBOR_EXPORT cbor_item_t **cbor_bytestring_chunks_handle( 78 const cbor_item_t *item); 79 80 /** Get the number of chunks this string consist of 81 * 82 * @param item[borrow] A indefinite bytestring 83 * @return The chunk count. 0 for freshly created items. 84 */ 85 CBOR_EXPORT size_t cbor_bytestring_chunk_count(const cbor_item_t *item); 86 87 /** Appends a chunk to the bytestring 88 * 89 * Indefinite byte strings only. 90 * 91 * May realloc the chunk storage. 92 * 93 * @param item[borrow] An indefinite byte string 94 * @param item[incref] A definite byte string 95 * @return true on success, false on realloc failure. In that case, the refcount 96 * of `chunk` is not increased and the `item` is left intact. 97 */ 98 CBOR_EXPORT bool cbor_bytestring_add_chunk(cbor_item_t *item, 99 cbor_item_t *chunk); 100 101 /** Creates a new definite byte string 102 * 103 * The handle is initialized to `NULL` and length to 0 104 * 105 * @return **new** definite bytestring. `NULL` on malloc failure. 106 */ 107 CBOR_EXPORT cbor_item_t *cbor_new_definite_bytestring(); 108 109 /** Creates a new indefinite byte string 110 * 111 * The chunks array is initialized to `NULL` and chunkcount to 0 112 * 113 * @return **new** indefinite bytestring. `NULL` on malloc failure. 114 */ 115 CBOR_EXPORT cbor_item_t *cbor_new_indefinite_bytestring(); 116 117 /** Creates a new byte string and initializes it 118 * 119 * The `handle` will be copied to a newly allocated block 120 * 121 * @param handle Block of binary data 122 * @param length Length of `data` 123 * @return A **new** byte string with content `handle`. `NULL` on malloc 124 * failure. 125 */ 126 CBOR_EXPORT cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length); 127 128 #ifdef __cplusplus 129 } 130 #endif 131 132 #endif // LIBCBOR_BYTESTRINGS_H 133