bytestrings.h revision 1.2 
1/*
2 * Copyright (c) 2014-2019 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
14extern "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 */
30size_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 */
37bool 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 */
44bool 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 */
55cbor_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 */
64void 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 */
76cbor_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 */
83size_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 */
96bool 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 */
104cbor_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 */
112cbor_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 */
123cbor_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