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 15 extern "C" { 16 #endif 17 18 /* 19 * ============================================================================ 20 * High level encoding 21 * ============================================================================ 22 */ 23 24 /** Serialize the given item 25 * 26 * @param item[borrow] 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[borrow] 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 45 cbor_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[borrow] A data item 59 * @param buffer[out] Buffer containing the result 60 * @param buffer_size[out] Size of the \p buffer, or ``NULL`` 61 * @return Length of the result. 0 on failure, in which case \p buffer is 62 * ``NULL``. 63 */ 64 CBOR_EXPORT size_t cbor_serialize_alloc(const cbor_item_t *item, 65 cbor_mutable_data *buffer, 66 size_t *buffer_size); 67 68 /** Serialize an uint 69 * 70 * @param item[borrow] A uint 71 * @param buffer Buffer to serialize to 72 * @param buffer_size Size of the \p buffer 73 * @return Length of the result. 0 on failure. 74 */ 75 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_uint(const cbor_item_t *, 76 cbor_mutable_data, 77 size_t); 78 79 /** Serialize a negint 80 * 81 * @param item[borrow] A negint 82 * @param buffer Buffer to serialize to 83 * @param buffer_size Size of the \p buffer 84 * @return Length of the result. 0 on failure. 85 */ 86 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_negint(const cbor_item_t *, 87 cbor_mutable_data, 88 size_t); 89 90 /** Serialize a bytestring 91 * 92 * @param item[borrow] A bytestring 93 * @param buffer Buffer to serialize to 94 * @param buffer_size Size of the \p buffer 95 * @return Length of the result. 0 on failure. 96 */ 97 _CBOR_NODISCARD CBOR_EXPORT size_t 98 cbor_serialize_bytestring(const cbor_item_t *, cbor_mutable_data, size_t); 99 100 /** Serialize a string 101 * 102 * @param item[borrow] A string 103 * @param buffer Buffer to serialize to 104 * @param buffer_size Size of the \p buffer 105 * @return Length of the result. 0 on failure. 106 */ 107 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_string(const cbor_item_t *, 108 cbor_mutable_data, 109 size_t); 110 111 /** Serialize an array 112 * 113 * @param item[borrow] An array 114 * @param buffer Buffer to serialize to 115 * @param buffer_size Size of the \p buffer 116 * @return Length of the result. 0 on failure. 117 */ 118 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_array(const cbor_item_t *, 119 cbor_mutable_data, 120 size_t); 121 122 /** Serialize a map 123 * 124 * @param item[borrow] A map 125 * @param buffer Buffer to serialize to 126 * @param buffer_size Size of the \p buffer 127 * @return Length of the result. 0 on failure. 128 */ 129 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_map(const cbor_item_t *, 130 cbor_mutable_data, 131 size_t); 132 133 /** Serialize a tag 134 * 135 * @param item[borrow] A tag 136 * @param buffer Buffer to serialize to 137 * @param buffer_size Size of the \p buffer 138 * @return Length of the result. 0 on failure. 139 */ 140 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_tag(const cbor_item_t *, 141 cbor_mutable_data, 142 size_t); 143 144 /** Serialize a 145 * 146 * @param item[borrow] A float or ctrl 147 * @param buffer Buffer to serialize to 148 * @param buffer_size Size of the \p buffer 149 * @return Length of the result. 0 on failure. 150 */ 151 _CBOR_NODISCARD CBOR_EXPORT size_t 152 cbor_serialize_float_ctrl(const cbor_item_t *, cbor_mutable_data, size_t); 153 154 #ifdef __cplusplus 155 } 156 #endif 157 158 #endif // LIBCBOR_SERIALIZATION_H 159