1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
/*
* Copyright (c) 2014-2020 Pavel Kalvoda <me@pavelkalvoda.com>
*
* libcbor is free software; you can redistribute it and/or modify
* it under the terms of the MIT license. See LICENSE for details.
*/
#ifndef LIBCBOR_BYTESTRINGS_H
#define LIBCBOR_BYTESTRINGS_H
#include "cbor/cbor_export.h"
#include "cbor/common.h"
#ifdef __cplusplus
extern "C" {
#endif
/*
* ============================================================================
* Byte string manipulation
* ============================================================================
*/
/** Returns the length of the binary data
*
* For definite byte strings only
*
* @param item a definite bytestring
* @return length of the binary data. Zero if no chunk has been attached yet
*/
_CBOR_NODISCARD
CBOR_EXPORT size_t cbor_bytestring_length(const cbor_item_t *item);
/** Is the byte string definite?
*
* @param item a byte string
* @return Is the byte string definite?
*/
_CBOR_NODISCARD
CBOR_EXPORT bool cbor_bytestring_is_definite(const cbor_item_t *item);
/** Is the byte string indefinite?
*
* @param item a byte string
* @return Is the byte string indefinite?
*/
_CBOR_NODISCARD
CBOR_EXPORT bool cbor_bytestring_is_indefinite(const cbor_item_t *item);
/** Get the handle to the binary data
*
* Definite items only. Modifying the data is allowed. In that case, the caller
* takes responsibility for the effect on items this item might be a part of
*
* @param item A definite byte string
* @return The address of the underlying binary data
* @return `NULL` if no data have been assigned
* yet.
*/
_CBOR_NODISCARD
CBOR_EXPORT cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item);
/** Set the handle to the binary data
*
* @param item A definite byte string
* @param data The memory block. The caller gives up the ownership of the block.
* libcbor will deallocate it when appropriate using the `free` implementation
* configured using #cbor_set_allocs
* @param length Length of the data block
*/
CBOR_EXPORT void cbor_bytestring_set_handle(
cbor_item_t *item, cbor_mutable_data CBOR_RESTRICT_POINTER data,
size_t length);
/** Get the handle to the array of chunks
*
* Manipulations with the memory block (e.g. sorting it) are allowed, but the
* validity and the number of chunks must be retained.
*
* @param item A indefinite byte string
* @return array of #cbor_bytestring_chunk_count definite bytestrings
*/
_CBOR_NODISCARD
CBOR_EXPORT cbor_item_t **cbor_bytestring_chunks_handle(
const cbor_item_t *item);
/** Get the number of chunks this string consist of
*
* @param item A indefinite bytestring
* @return The chunk count. 0 for freshly created items.
*/
_CBOR_NODISCARD
CBOR_EXPORT size_t cbor_bytestring_chunk_count(const cbor_item_t *item);
/** Appends a chunk to the bytestring
*
* Indefinite byte strings only.
*
* May realloc the chunk storage.
*
* @param item An indefinite byte string
* @param chunk A definite byte string. Its reference count will be be increased
* by one.
* @return true on success, false on realloc failure. In that case, the refcount
* of `chunk` is not increased and the `item` is left intact.
*/
_CBOR_NODISCARD
CBOR_EXPORT bool cbor_bytestring_add_chunk(cbor_item_t *item,
cbor_item_t *chunk);
/** Creates a new definite byte string
*
* The handle is initialized to `NULL` and length to 0
*
* @return Reference to the new bytestring item. The item's reference count is
* initialized to one.
* @return `NULL` if memory allocation fails
*/
_CBOR_NODISCARD
CBOR_EXPORT cbor_item_t *cbor_new_definite_bytestring(void);
/** Creates a new indefinite byte string
*
* The chunks array is initialized to `NULL` and chunk count to 0
*
* @return Reference to the new bytestring item. The item's reference count is
* initialized to one.
* @return `NULL` if memory allocation fails
*/
_CBOR_NODISCARD
CBOR_EXPORT cbor_item_t *cbor_new_indefinite_bytestring(void);
/** Creates a new byte string and initializes it
*
* The `handle` will be copied to a newly allocated block
*
* @param handle Block of binary data
* @param length Length of `data`
* @return Reference to the new bytestring item. The item's reference count is
* initialized to one.
* @return `NULL` if memory allocation fails
*/
_CBOR_NODISCARD
CBOR_EXPORT cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length);
#ifdef __cplusplus
}
#endif
#endif // LIBCBOR_BYTESTRINGS_H
|
