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