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:: 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 */ 65 CBOR_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