1 /* 2 * Copyright (c) 2022-2023 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #ifndef H_ZCBOR_BULK_PRIV_ 7 #define H_ZCBOR_BULK_PRIV_ 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 #include <zephyr/toolchain.h> 14 15 /** @cond INTERNAL_HIDDEN */ 16 17 struct zcbor_map_decode_key_val { 18 struct zcbor_string key; /* Map key string */ 19 zcbor_decoder_t *decoder; /* Key corresponding decoder */ 20 void *value_ptr; 21 bool found; 22 }; 23 24 /** @brief Define single key-decoder mapping 25 * 26 * The macro creates a single zcbor_map_decode_key_val type object. 27 * 28 * @param k key is "" enclosed string representing key; 29 * @param dec decoder function; this should be zcbor_decoder_t 30 * type function from zcbor or a user provided implementation 31 * compatible with the type. 32 * @param vp non-NULL pointer for result of decoding; should correspond 33 * to type served by decoder function for the mapping. 34 */ 35 #define ZCBOR_MAP_DECODE_KEY_DECODER(k, dec, vp) \ 36 { \ 37 { \ 38 .value = k, \ 39 .len = sizeof(k) - 1, \ 40 }, \ 41 .decoder = (zcbor_decoder_t *)dec, \ 42 .value_ptr = vp, \ 43 .found = false, \ 44 } 45 46 /** @brief Define single key-value decode mapping 47 * 48 * ZCBOR_MAP_DECODE_KEY_DECODER should be used instead of this macro as, 49 * this macro does not allow keys with whitespaces embeeded, which CBOR 50 * does allow. 51 * 52 * The macro creates a single zcbor_map_decode_key_val type object. 53 * 54 * @param k key; the @p k will be stringified so should be given 55 * without ""; 56 * @param dec decoder function; this should be zcbor_decoder_t 57 * type function from zcbor or a user provided implementation 58 * compatible with the type. 59 * @param vp non-NULL pointer for result of decoding; should correspond 60 * to type served by decoder function for the mapping. 61 */ 62 #define ZCBOR_MAP_DECODE_KEY_VAL(k, dec, vp) \ 63 ZCBOR_MAP_DECODE_KEY_DECODER(STRINGIFY(k), dec, vp) 64 65 /** @brief Decodes single level map according to a provided key-decode map. 66 * 67 * The function takes @p map of key to decoder array defined as: 68 * 69 * struct zcbor_map_decode_key_val map[] = { 70 * ZCBOR_MAP_DECODE_KEY_DECODER("key0", decode_fun0, val_ptr0), 71 * ZCBOR_MAP_DECODE_KEY_DECODER("key1", decode_fun1, val_ptr1), 72 * ... 73 * }; 74 * 75 * where "key?" is string representing key; the decode_fun? is 76 * zcbor_decoder_t compatible function, either from zcbor or defined by 77 * user; val_ptr? are pointers to variables where decoder function for 78 * a given key will place a decoded value - they have to agree in type 79 * with decoder function. 80 * 81 * Failure to decode any of values will cause the function to return 82 * negative error, and leave the map open: map is broken anyway or key-decoder 83 * mapping is broken, and we can not really decode the map. 84 * 85 * Note that the function opens map by itself and will fail if map 86 * is already opened. 87 * 88 * @param zsd zcbor decoder state; 89 * @param map key-decoder mapping list; 90 * @param map_size size of maps, both maps have to have the same size; 91 * @param matched pointer to the counter of matched keys, zeroed upon 92 * successful map entry and incremented only for successful 93 * decoded fields. 94 * @return 0 when the whole map has been parsed, there have been 95 * no decoding errors, and map has been closed successfully; 96 * -ENOMSG when given decoder function failed to decode 97 * value; 98 * -EADDRINUSE when key appears twice within map, map is then 99 * parsed up to they key that has appeared twice; 100 * -EBADMSG when failed to close map. 101 */ 102 int zcbor_map_decode_bulk(zcbor_state_t *zsd, struct zcbor_map_decode_key_val *map, 103 size_t map_size, size_t *matched); 104 105 /** @brief Check whether key has been found by zcbor_map_decode_bulk 106 * 107 * @param map key-decoder mapping list; 108 * @param map_size size of maps, both maps have to have the same size; 109 * @param key string representing key to check with map. 110 * 111 * @return true if key has been found during decoding, false otherwise. 112 * 113 */ 114 bool zcbor_map_decode_bulk_key_found(struct zcbor_map_decode_key_val *map, 115 size_t map_size, const char *key); 116 117 /** @brief Reset decoding state of key-value 118 * 119 * The function takes @p map and resets internal fields that mark decoding state 120 * of the map. Function needs to be used on @p map after the map has been already 121 * used for decoding other buffer, otherwise decoding may fail. 122 * 123 * @param map key-decoder mapping list; 124 * @param map_size size of maps, both maps have to have the same size. 125 * 126 * @return Nothing. 127 */ 128 void zcbor_map_decode_bulk_reset(struct zcbor_map_decode_key_val *map, size_t map_size); 129 130 /** @endcond */ 131 132 #ifdef __cplusplus 133 } 134 #endif 135 136 #endif /* H_ZCBOR_BULK_PRIV_ */ 137
