deimos.cbor.bytestrings source code

1 module deimos.cbor.bytestrings;
2 
3 import deimos.cbor.data;
4 
5 /*
6  * Copyright (c) 2014-2019 Pavel Kalvoda <me@pavelkalvoda.com>
7  *
8  * libcbor is free software; you can redistribute it and/or modify
9  * it under the terms of the MIT license. See LICENSE for details.
10  */
11 
12 extern (C):
13 
14 /*
15  * ============================================================================
16  * Byte string manipulation
17  * ============================================================================
18  */
19 
20 /** Returns the length of the binary data
21  *
22  * For definite byte strings only
23  *
24  * @param item[borrow] a definite bytestring
25  * @return length of the binary data. Zero if no chunk has been attached yet
26  */
27 size_t cbor_bytestring_length(const cbor_item_t* item);
28 
29 /** Is the byte string definite?
30  *
31  * @param item[borrow] a byte string
32  * @return Is the byte string definite?
33  */
34 bool cbor_bytestring_is_definite(const cbor_item_t* item);
35 
36 /** Is the byte string indefinite?
37  *
38  * @param item[borrow] a byte string
39  * @return Is the byte string indefinite?
40  */
41 bool cbor_bytestring_is_indefinite(const cbor_item_t* item);
42 
43 /** Get the handle to the binary data
44  *
45  * Definite items only. Modifying the data is allowed. In that case, the caller
46  * takes responsibility for the effect on items this item might be a part of
47  *
48  * @param item[borrow] A definite byte string
49  * @return The address of the binary data. `NULL` if no data have been assigned
50  * yet.
51  */
52 cbor_mutable_data cbor_bytestring_handle(const cbor_item_t* item);
53 
54 /** Set the handle to the binary data
55  *
56  * @param item[borrow] A definite byte string
57  * @param data The memory block. The caller gives up the ownership of the block.
58  * libcbor will deallocate it when appropriate using its free function
59  * @param length Length of the data block
60  */
61 void cbor_bytestring_set_handle(cbor_item_t* item, cbor_mutable_data data, size_t length);
62 
63 /** Get the handle to the array of chunks
64  *
65  * Manipulations with the memory block (e.g. sorting it) are allowed, but the
66  * validity and the number of chunks must be retained.
67  *
68  * @param item[borrow] A indefinite byte string
69  * @return array of #cbor_bytestring_chunk_count definite bytestrings
70  */
71 cbor_item_t** cbor_bytestring_chunks_handle(const cbor_item_t* item);
72 
73 /** Get the number of chunks this string consist of
74  *
75  * @param item[borrow] A indefinite bytestring
76  * @return The chunk count. 0 for freshly created items.
77  */
78 size_t cbor_bytestring_chunk_count(const cbor_item_t* item);
79 
80 /** Appends a chunk to the bytestring
81  *
82  * Indefinite byte strings only.
83  *
84  * May realloc the chunk storage.
85  *
86  * @param item[borrow] An indefinite byte string
87  * @param item[incref] A definite byte string
88  * @return true on success, false on realloc failure. In that case, the refcount
89  * of `chunk` is not increased and the `item` is left intact.
90  */
91 bool cbor_bytestring_add_chunk(cbor_item_t* item, cbor_item_t* chunk);
92 
93 /** Creates a new definite byte string
94  *
95  * The handle is initialized to `NULL` and length to 0
96  *
97  * @return **new** definite bytestring. `NULL` on malloc failure.
98  */
99 cbor_item_t* cbor_new_definite_bytestring();
100 
101 /** Creates a new indefinite byte string
102  *
103  * The chunks array is initialized to `NULL` and chunkcount to 0
104  *
105  * @return **new** indefinite bytestring. `NULL` on malloc failure.
106  */
107 cbor_item_t* cbor_new_indefinite_bytestring();
108 
109 /** Creates a new byte string and initializes it
110  *
111  * The `handle` will be copied to a newly allocated block
112  *
113  * @param handle Block of binary data
114  * @param length Length of `data`
115  * @return A **new** byte string with content `handle`. `NULL` on malloc
116  * failure.
117  */
118 cbor_item_t* cbor_build_bytestring(cbor_data handle, size_t length);