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