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_SERIALIZATION_H
9#define LIBCBOR_SERIALIZATION_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 * High level encoding
21 * ============================================================================
22 */
23
24/** Serialize the given item
25 *
26 * @param item A data item
27 * @param buffer Buffer to serialize to
28 * @param buffer_size Size of the \p buffer
29 * @return Length of the result. 0 on failure.
30 */
31_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize(const cbor_item_t *item,
32                                                  cbor_mutable_data buffer,
33                                                  size_t buffer_size);
34
35/** Compute the length (in bytes) of the item when serialized using
36 * `cbor_serialize`.
37 *
38 * Time complexity is proportional to the number of nested items.
39 *
40 * @param item A data item
41 * @return Length (>= 1) of the item when serialized. 0 if the length overflows
42 * `size_t`.
43 */
44_CBOR_NODISCARD CBOR_EXPORT size_t
45cbor_serialized_size(const cbor_item_t *item);
46
47/** Serialize the given item, allocating buffers as needed
48 *
49 * Since libcbor v0.10, the return value is always the same as `buffer_size` (if
50 * provided, see https://github.com/PJK/libcbor/pull/251/). New clients should
51 * ignore the return value.
52 *
53 * \rst
54 * .. warning:: It is the caller's responsibility to free the buffer using an
55 *  appropriate ``free`` implementation.
56 * \endrst
57 *
58 * @param item A data item
59 * @param[out] buffer Buffer containing the result
60 * @param[out] buffer_size Size of the \p buffer, or 0 on memory allocation
61 * failure.
62 * @return Length of the result in bytes
63 * @return 0 on memory allocation failure, in which case \p buffer is `NULL`.
64 */
65CBOR_EXPORT size_t cbor_serialize_alloc(const cbor_item_t *item,
66                                        unsigned char **buffer,
67                                        size_t *buffer_size);
68
69/** Serialize an uint
70 *
71 * @param item A uint
72 * @param[out] buffer Buffer to serialize to
73 * @param buffer_size Size of the \p buffer
74 * @return Length of the result
75 * @return 0 if the \p buffer_size doesn't fit the result
76 */
77_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_uint(const cbor_item_t *item,
78                                                       cbor_mutable_data buffer,
79                                                       size_t buffer_size);
80
81/** Serialize a negint
82 *
83 * @param item A negint
84 * @param[out] buffer Buffer to serialize to
85 * @param buffer_size Size of the \p buffer
86 * @return Length of the result
87 * @return 0 if the \p buffer_size doesn't fit the result
88 */
89_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_negint(
90    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
91
92/** Serialize a bytestring
93 *
94 * @param item A bytestring
95 * @param[out] buffer Buffer to serialize to
96 * @param buffer_size Size of the \p buffer
97 * @return Length of the result
98 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
99 * still be modified
100 */
101_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_bytestring(
102    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
103
104/** Serialize a string
105 *
106 * @param item A string
107 * @param[out] buffer Buffer to serialize to
108 * @param buffer_size Size of the \p buffer
109 * @return Length of the result
110 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
111 * still be modified
112 */
113_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_string(
114    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
115/** Serialize an array
116 *
117 * @param item An array
118 * @param[out] buffer Buffer to serialize to
119 * @param buffer_size Size of the \p buffer
120 * @return Length of the result
121 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
122 * still be modified
123 */
124_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_array(
125    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
126
127/** Serialize a map
128 *
129 * @param item A map
130 * @param[out] buffer Buffer to serialize to
131 * @param buffer_size Size of the \p buffer
132 * @return Length of the result
133 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
134 * still be modified
135 */
136_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_map(const cbor_item_t *item,
137                                                      cbor_mutable_data buffer,
138                                                      size_t buffer_size);
139
140/** Serialize a tag
141 *
142 * @param item A tag
143 * @param[out] buffer Buffer to serialize to
144 * @param buffer_size Size of the \p buffer
145 * @return Length of the result
146 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
147 * still be modified
148 */
149_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_tag(const cbor_item_t *item,
150                                                      cbor_mutable_data buffer,
151                                                      size_t buffer_size);
152
153/** Serialize a
154 *
155 * @param item A float or ctrl
156 * @param[out] buffer Buffer to serialize to
157 * @param buffer_size Size of the \p buffer
158 * @return Length of the result
159 * @return 0 if the \p buffer_size doesn't fit the result
160 */
161_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_float_ctrl(
162    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
163
164#ifdef __cplusplus
165}
166#endif
167
168#endif  // LIBCBOR_SERIALIZATION_H
169