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 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 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:: 55 * It is the caller's responsibility to free the buffer using an appropriate 56 * ``free`` implementation. 57 * \endrst 58 * 59 * @param item A data item 60 * @param[out] buffer Buffer containing the result 61 * @param[out] buffer_size Size of the \p buffer, or 0 on memory allocation 62 * failure. 63 * @return Length of the result in bytes 64 * @return 0 on memory allocation failure, in which case \p buffer is `NULL`. 65 */ 66 CBOR_EXPORT size_t cbor_serialize_alloc(const cbor_item_t* item, 67 unsigned char** buffer, 68 size_t* buffer_size); 69 70 /** Serialize an uint 71 * 72 * @param item A uint 73 * @param[out] buffer Buffer to serialize to 74 * @param buffer_size Size of the \p buffer 75 * @return Length of the result 76 * @return 0 if the \p buffer_size doesn't fit the result 77 */ 78 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_uint(const cbor_item_t* item, 79 cbor_mutable_data buffer, 80 size_t buffer_size); 81 82 /** Serialize a negint 83 * 84 * @param item A negint 85 * @param[out] buffer Buffer to serialize to 86 * @param buffer_size Size of the \p buffer 87 * @return Length of the result 88 * @return 0 if the \p buffer_size doesn't fit the result 89 */ 90 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_negint( 91 const cbor_item_t* item, cbor_mutable_data buffer, size_t buffer_size); 92 93 /** Serialize a bytestring 94 * 95 * @param item A bytestring 96 * @param[out] buffer Buffer to serialize to 97 * @param buffer_size Size of the \p buffer 98 * @return Length of the result 99 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may 100 * still be modified 101 */ 102 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_bytestring( 103 const cbor_item_t* item, cbor_mutable_data buffer, size_t buffer_size); 104 105 /** Serialize a string 106 * 107 * @param item A string 108 * @param[out] buffer Buffer to serialize to 109 * @param buffer_size Size of the \p buffer 110 * @return Length of the result 111 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may 112 * still be modified 113 */ 114 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_string( 115 const cbor_item_t* item, cbor_mutable_data buffer, size_t buffer_size); 116 /** Serialize an array 117 * 118 * @param item An array 119 * @param[out] buffer Buffer to serialize to 120 * @param buffer_size Size of the \p buffer 121 * @return Length of the result 122 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may 123 * still be modified 124 */ 125 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_array( 126 const cbor_item_t* item, cbor_mutable_data buffer, size_t buffer_size); 127 128 /** Serialize a map 129 * 130 * @param item A map 131 * @param[out] buffer Buffer to serialize to 132 * @param buffer_size Size of the \p buffer 133 * @return Length of the result 134 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may 135 * still be modified 136 */ 137 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_map(const cbor_item_t* item, 138 cbor_mutable_data buffer, 139 size_t buffer_size); 140 141 /** Serialize a tag 142 * 143 * @param item A tag 144 * @param[out] buffer Buffer to serialize to 145 * @param buffer_size Size of the \p buffer 146 * @return Length of the result 147 * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may 148 * still be modified 149 */ 150 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_tag(const cbor_item_t* item, 151 cbor_mutable_data buffer, 152 size_t buffer_size); 153 154 /** Serialize a 155 * 156 * @param item A float or ctrl 157 * @param[out] buffer Buffer to serialize to 158 * @param buffer_size Size of the \p buffer 159 * @return Length of the result 160 * @return 0 if the \p buffer_size doesn't fit the result 161 */ 162 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_float_ctrl( 163 const cbor_item_t* item, cbor_mutable_data buffer, size_t buffer_size); 164 165 #ifdef __cplusplus 166 } 167 #endif 168 169 #endif // LIBCBOR_SERIALIZATION_H 170