2 * Copyright (c) 2014-2020 Pavel Kalvoda <me@pavelkalvoda.com>
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.
8 #ifndef LIBCBOR_BYTESTRINGS_H
9 #define LIBCBOR_BYTESTRINGS_H
11 #include "cbor/cbor_export.h"
12 #include "cbor/common.h"
19 * ============================================================================
20 * Byte string manipulation
21 * ============================================================================
24 /** Returns the length of the binary data
26 * For definite byte strings only
28 * @param item[borrow] a definite bytestring
29 * @return length of the binary data. Zero if no chunk has been attached yet
31 CBOR_EXPORT size_t cbor_bytestring_length(const cbor_item_t *item);
33 /** Is the byte string definite?
35 * @param item[borrow] a byte string
36 * @return Is the byte string definite?
38 CBOR_EXPORT bool cbor_bytestring_is_definite(const cbor_item_t *item);
40 /** Is the byte string indefinite?
42 * @param item[borrow] a byte string
43 * @return Is the byte string indefinite?
45 CBOR_EXPORT bool cbor_bytestring_is_indefinite(const cbor_item_t *item);
47 /** Get the handle to the binary data
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
52 * @param item[borrow] A definite byte string
53 * @return The address of the binary data. `NULL` if no data have been assigned
56 CBOR_EXPORT cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item);
58 /** Set the handle to the binary data
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
65 CBOR_EXPORT void cbor_bytestring_set_handle(
66 cbor_item_t *item, cbor_mutable_data CBOR_RESTRICT_POINTER data,
69 /** Get the handle to the array of chunks
71 * Manipulations with the memory block (e.g. sorting it) are allowed, but the
72 * validity and the number of chunks must be retained.
74 * @param item[borrow] A indefinite byte string
75 * @return array of #cbor_bytestring_chunk_count definite bytestrings
77 CBOR_EXPORT cbor_item_t **cbor_bytestring_chunks_handle(
78 const cbor_item_t *item);
80 /** Get the number of chunks this string consist of
82 * @param item[borrow] A indefinite bytestring
83 * @return The chunk count. 0 for freshly created items.
85 CBOR_EXPORT size_t cbor_bytestring_chunk_count(const cbor_item_t *item);
87 /** Appends a chunk to the bytestring
89 * Indefinite byte strings only.
91 * May realloc the chunk storage.
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.
98 CBOR_EXPORT bool cbor_bytestring_add_chunk(cbor_item_t *item,
101 /** Creates a new definite byte string
103 * The handle is initialized to `NULL` and length to 0
105 * @return **new** definite bytestring. `NULL` on malloc failure.
107 CBOR_EXPORT cbor_item_t *cbor_new_definite_bytestring();
109 /** Creates a new indefinite byte string
111 * The chunks array is initialized to `NULL` and chunkcount to 0
113 * @return **new** indefinite bytestring. `NULL` on malloc failure.
115 CBOR_EXPORT cbor_item_t *cbor_new_indefinite_bytestring();
117 /** Creates a new byte string and initializes it
119 * The `handle` will be copied to a newly allocated block
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
126 CBOR_EXPORT cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length);
132 #endif // LIBCBOR_BYTESTRINGS_H