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