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_TAGS_H 9 #define LIBCBOR_TAGS_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 * Tag manipulation 21 * ============================================================================ 22 */ 23 24 /** Create a new tag. 25 * 26 * @param value The tag value (number). 27 * @return Reference to the new tag. Its reference count is initialized to one 28 * and it points to a `NULL` item. 29 * @return `NULL` if memory allocation fails. 30 */ 31 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t* cbor_new_tag(uint64_t value); 32 33 /** Get the tagged item (what the tag points to). 34 * 35 * @param tag A #CBOR_TYPE_TAG tag. 36 * @return Reference to the tagged item. 37 * 38 * Increases the reference count of the underlying item. The returned reference 39 * must be released using #cbor_decref. 40 */ 41 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t* cbor_tag_item(const cbor_item_t* tag); 42 43 /** Get the tag value. 44 * 45 * @param tag A #CBOR_TYPE_TAG tag. 46 * @return The tag value (number). 47 */ 48 _CBOR_NODISCARD CBOR_EXPORT uint64_t cbor_tag_value(const cbor_item_t* tag); 49 50 /** Assign a tag to an item. 51 * 52 * @param tag A #CBOR_TYPE_TAG tag. 53 * @param tagged_item The item to tag. Its reference count will be increased 54 * by one. 55 * 56 * If the tag already points to an item, the pointer will be replaced, without a 57 * reference count change on the previous item. 58 * TODO: Should we release the reference automatically? 59 */ 60 CBOR_EXPORT void cbor_tag_set_item(cbor_item_t* tag, cbor_item_t* tagged_item); 61 62 /** Build a new tag. 63 * 64 * @param item The item to tag. Its reference count will be increased by 65 * one. 66 * @param value The tag value (number). 67 * @return Reference to the new tag item. The item's reference count is 68 * initialized to one. 69 * @return `NULL` if memory allocation fails. 70 */ 71 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t* cbor_build_tag(uint64_t value, 72 cbor_item_t* item); 73 74 #ifdef __cplusplus 75 } 76 #endif 77 78 #endif // LIBCBOR_TAGS_H 79