Xin Zhang / azure-iot-c-sdk-f767zi

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   samplemqtt

c-utility/inc/azure_c_shared_utility/map.h@0:f7f1f0d76dd6, 2018-08-23 (annotated)

Committer:
XinZhangMS
Date:
Thu Aug 23 06:52:14 2018 +0000
Revision:
0:f7f1f0d76dd6
azure-c-sdk for mbed os supporting NUCLEO_F767ZI

Who changed what in which revision?

UserRevisionLine numberNew contents of line
XinZhangMS 0:f7f1f0d76dd6 1 // Copyright (c) Microsoft. All rights reserved.
XinZhangMS 0:f7f1f0d76dd6 2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
XinZhangMS 0:f7f1f0d76dd6 3
XinZhangMS 0:f7f1f0d76dd6 4 /** @file map.h
XinZhangMS 0:f7f1f0d76dd6 5 * @brief Map is a module that implements a dictionary of @c STRING_HANDLE
XinZhangMS 0:f7f1f0d76dd6 6 * keys to @c STRING_HANDLE values.
XinZhangMS 0:f7f1f0d76dd6 7 */
XinZhangMS 0:f7f1f0d76dd6 8
XinZhangMS 0:f7f1f0d76dd6 9 #ifndef MAP_H
XinZhangMS 0:f7f1f0d76dd6 10 #define MAP_H
XinZhangMS 0:f7f1f0d76dd6 11
XinZhangMS 0:f7f1f0d76dd6 12 #include "azure_c_shared_utility/macro_utils.h"
XinZhangMS 0:f7f1f0d76dd6 13 #include "azure_c_shared_utility/strings.h"
XinZhangMS 0:f7f1f0d76dd6 14 #include "azure_c_shared_utility/crt_abstractions.h"
XinZhangMS 0:f7f1f0d76dd6 15 #include "azure_c_shared_utility/umock_c_prod.h"
XinZhangMS 0:f7f1f0d76dd6 16
XinZhangMS 0:f7f1f0d76dd6 17 #ifdef __cplusplus
XinZhangMS 0:f7f1f0d76dd6 18 #include <cstddef>
XinZhangMS 0:f7f1f0d76dd6 19 extern "C"
XinZhangMS 0:f7f1f0d76dd6 20 {
XinZhangMS 0:f7f1f0d76dd6 21 #else
XinZhangMS 0:f7f1f0d76dd6 22 #include <stddef.h>
XinZhangMS 0:f7f1f0d76dd6 23 #endif
XinZhangMS 0:f7f1f0d76dd6 24
XinZhangMS 0:f7f1f0d76dd6 25 #define MAP_RESULT_VALUES \
XinZhangMS 0:f7f1f0d76dd6 26 MAP_OK, \
XinZhangMS 0:f7f1f0d76dd6 27 MAP_ERROR, \
XinZhangMS 0:f7f1f0d76dd6 28 MAP_INVALIDARG, \
XinZhangMS 0:f7f1f0d76dd6 29 MAP_KEYEXISTS, \
XinZhangMS 0:f7f1f0d76dd6 30 MAP_KEYNOTFOUND, \
XinZhangMS 0:f7f1f0d76dd6 31 MAP_FILTER_REJECT
XinZhangMS 0:f7f1f0d76dd6 32
XinZhangMS 0:f7f1f0d76dd6 33 /** @brief Enumeration specifying the status of calls to various APIs in this
XinZhangMS 0:f7f1f0d76dd6 34 * module.
XinZhangMS 0:f7f1f0d76dd6 35 */
XinZhangMS 0:f7f1f0d76dd6 36 DEFINE_ENUM(MAP_RESULT, MAP_RESULT_VALUES);
XinZhangMS 0:f7f1f0d76dd6 37
XinZhangMS 0:f7f1f0d76dd6 38 typedef struct MAP_HANDLE_DATA_TAG* MAP_HANDLE;
XinZhangMS 0:f7f1f0d76dd6 39
XinZhangMS 0:f7f1f0d76dd6 40 typedef int (*MAP_FILTER_CALLBACK)(const char* mapProperty, const char* mapValue);
XinZhangMS 0:f7f1f0d76dd6 41
XinZhangMS 0:f7f1f0d76dd6 42 /**
XinZhangMS 0:f7f1f0d76dd6 43 * @brief Creates a new, empty map.
XinZhangMS 0:f7f1f0d76dd6 44 *
XinZhangMS 0:f7f1f0d76dd6 45 * @param mapFilterFunc A callback function supplied by the caller that is
XinZhangMS 0:f7f1f0d76dd6 46 * invoked during calls to ::Map_Add and
XinZhangMS 0:f7f1f0d76dd6 47 * ::Map_AddOrUpdate to provide the caller an
XinZhangMS 0:f7f1f0d76dd6 48 * opportunity to indicate whether the new entry or
XinZhangMS 0:f7f1f0d76dd6 49 * the update to an existing entry can be made or not.
XinZhangMS 0:f7f1f0d76dd6 50 * The callback function can request that the operation
XinZhangMS 0:f7f1f0d76dd6 51 * be canceled by returning a non-zero value from the
XinZhangMS 0:f7f1f0d76dd6 52 * callback.
XinZhangMS 0:f7f1f0d76dd6 53 *
XinZhangMS 0:f7f1f0d76dd6 54 * @return A valid @c MAP_HANDLE or @c NULL in case an error occurs.
XinZhangMS 0:f7f1f0d76dd6 55 */
XinZhangMS 0:f7f1f0d76dd6 56 MOCKABLE_FUNCTION(, MAP_HANDLE, Map_Create, MAP_FILTER_CALLBACK, mapFilterFunc);
XinZhangMS 0:f7f1f0d76dd6 57
XinZhangMS 0:f7f1f0d76dd6 58 /**
XinZhangMS 0:f7f1f0d76dd6 59 * @brief Release all resources associated with the map.
XinZhangMS 0:f7f1f0d76dd6 60 *
XinZhangMS 0:f7f1f0d76dd6 61 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 62 */
XinZhangMS 0:f7f1f0d76dd6 63 MOCKABLE_FUNCTION(, void, Map_Destroy, MAP_HANDLE, handle);
XinZhangMS 0:f7f1f0d76dd6 64
XinZhangMS 0:f7f1f0d76dd6 65 /**
XinZhangMS 0:f7f1f0d76dd6 66 * @brief Creates a copy of the map indicated by @p handle and returns a
XinZhangMS 0:f7f1f0d76dd6 67 * handle to it.
XinZhangMS 0:f7f1f0d76dd6 68 *
XinZhangMS 0:f7f1f0d76dd6 69 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 70 *
XinZhangMS 0:f7f1f0d76dd6 71 * @return A valid @c MAP_HANDLE to the cloned copy of the map or @c NULL
XinZhangMS 0:f7f1f0d76dd6 72 * in case an error occurs.
XinZhangMS 0:f7f1f0d76dd6 73 */
XinZhangMS 0:f7f1f0d76dd6 74 MOCKABLE_FUNCTION(, MAP_HANDLE, Map_Clone, MAP_HANDLE, handle);
XinZhangMS 0:f7f1f0d76dd6 75
XinZhangMS 0:f7f1f0d76dd6 76 /**
XinZhangMS 0:f7f1f0d76dd6 77 * @brief Adds a key/value pair to the map.
XinZhangMS 0:f7f1f0d76dd6 78 *
XinZhangMS 0:f7f1f0d76dd6 79 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 80 * @param key The @c key to be used for this map entry.
XinZhangMS 0:f7f1f0d76dd6 81 * @param value The @c value to be associated with @p key.
XinZhangMS 0:f7f1f0d76dd6 82 *
XinZhangMS 0:f7f1f0d76dd6 83 * If a non-NULL pointer to a callback function was supplied
XinZhangMS 0:f7f1f0d76dd6 84 * via the @c mapFilterFunc parameter when ::Map_Create was
XinZhangMS 0:f7f1f0d76dd6 85 * called then that callback is invoked when a new entry is
XinZhangMS 0:f7f1f0d76dd6 86 * added and if the callback returns a non-zero value then
XinZhangMS 0:f7f1f0d76dd6 87 * the function cancels the add operation and returns
XinZhangMS 0:f7f1f0d76dd6 88 * @c MAP_FILTER_REJECT.
XinZhangMS 0:f7f1f0d76dd6 89 *
XinZhangMS 0:f7f1f0d76dd6 90 * @return If any of the input parameters are @c NULL then this function
XinZhangMS 0:f7f1f0d76dd6 91 * returns @c MAP_INVALID_ARG. If the key already exists in the
XinZhangMS 0:f7f1f0d76dd6 92 * map then @c MAP_KEYEXISTS is returned. If the filter function
XinZhangMS 0:f7f1f0d76dd6 93 * associated with the map rejects the entry then
XinZhangMS 0:f7f1f0d76dd6 94 * @c MAP_FILTER_REJECT is returned. In case an error occurs when
XinZhangMS 0:f7f1f0d76dd6 95 * the new key is added to the map the function returns @c MAP_ERROR.
XinZhangMS 0:f7f1f0d76dd6 96 * If everything goes well then @c MAP_OK is returned.
XinZhangMS 0:f7f1f0d76dd6 97 */
XinZhangMS 0:f7f1f0d76dd6 98 MOCKABLE_FUNCTION(, MAP_RESULT, Map_Add, MAP_HANDLE, handle, const char*, key, const char*, value);
XinZhangMS 0:f7f1f0d76dd6 99
XinZhangMS 0:f7f1f0d76dd6 100 /**
XinZhangMS 0:f7f1f0d76dd6 101 * @brief Adds/updates a key/value pair to the map.
XinZhangMS 0:f7f1f0d76dd6 102 *
XinZhangMS 0:f7f1f0d76dd6 103 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 104 * @param key The @c key to be used for this map entry.
XinZhangMS 0:f7f1f0d76dd6 105 * @param value The @c value to be associated with @p key.
XinZhangMS 0:f7f1f0d76dd6 106 *
XinZhangMS 0:f7f1f0d76dd6 107 * This function behaves exactly like ::Map_Add except that if the key
XinZhangMS 0:f7f1f0d76dd6 108 * already exists in the map then it overwrites the value with the
XinZhangMS 0:f7f1f0d76dd6 109 * supplied value instead of returning an error. If a non-NULL pointer
XinZhangMS 0:f7f1f0d76dd6 110 * to a callback function was supplied via the @c mapFilterFunc parameter
XinZhangMS 0:f7f1f0d76dd6 111 * when ::Map_Create was called then that callback is invoked when a new
XinZhangMS 0:f7f1f0d76dd6 112 * entry is added or when an existing entry is updated and if the
XinZhangMS 0:f7f1f0d76dd6 113 * callback returns a non-zero value then the function cancels the
XinZhangMS 0:f7f1f0d76dd6 114 * add/update operation and returns @c MAP_FILTER_REJECT.
XinZhangMS 0:f7f1f0d76dd6 115 *
XinZhangMS 0:f7f1f0d76dd6 116 * @return If any of the input parameters are @c NULL then this function
XinZhangMS 0:f7f1f0d76dd6 117 * returns @c MAP_INVALID_ARG. If the filter function associated
XinZhangMS 0:f7f1f0d76dd6 118 * with the map rejects the entry then @c MAP_FILTER_REJECT is
XinZhangMS 0:f7f1f0d76dd6 119 * returned. In case an error occurs when the new key is
XinZhangMS 0:f7f1f0d76dd6 120 * added/updated in the map the function returns @c MAP_ERROR. If
XinZhangMS 0:f7f1f0d76dd6 121 * everything goes well then @c MAP_OK is returned.
XinZhangMS 0:f7f1f0d76dd6 122 */
XinZhangMS 0:f7f1f0d76dd6 123 MOCKABLE_FUNCTION(, MAP_RESULT, Map_AddOrUpdate, MAP_HANDLE, handle, const char*, key, const char*, value);
XinZhangMS 0:f7f1f0d76dd6 124
XinZhangMS 0:f7f1f0d76dd6 125 /**
XinZhangMS 0:f7f1f0d76dd6 126 * @brief Removes a key and its associated value from the map.
XinZhangMS 0:f7f1f0d76dd6 127 *
XinZhangMS 0:f7f1f0d76dd6 128 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 129 * @param key The @c key of the item to be deleted.
XinZhangMS 0:f7f1f0d76dd6 130 *
XinZhangMS 0:f7f1f0d76dd6 131 * @return Returns @c MAP_OK if the key was deleted successfully or an
XinZhangMS 0:f7f1f0d76dd6 132 * error code otherwise.
XinZhangMS 0:f7f1f0d76dd6 133 */
XinZhangMS 0:f7f1f0d76dd6 134 MOCKABLE_FUNCTION(, MAP_RESULT, Map_Delete, MAP_HANDLE, handle, const char*, key);
XinZhangMS 0:f7f1f0d76dd6 135
XinZhangMS 0:f7f1f0d76dd6 136 /**
XinZhangMS 0:f7f1f0d76dd6 137 * @brief This function returns a boolean value in @p keyExists if the map
XinZhangMS 0:f7f1f0d76dd6 138 * contains a key with the same value the parameter @p key.
XinZhangMS 0:f7f1f0d76dd6 139 *
XinZhangMS 0:f7f1f0d76dd6 140 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 141 * @param key The key that the caller wants checked.
XinZhangMS 0:f7f1f0d76dd6 142 * @param keyExists The function writes @c true at the address pointed at
XinZhangMS 0:f7f1f0d76dd6 143 * by this parameter if the key exists in the map and
XinZhangMS 0:f7f1f0d76dd6 144 * @c false otherwise.
XinZhangMS 0:f7f1f0d76dd6 145 *
XinZhangMS 0:f7f1f0d76dd6 146 * @return Returns @c MAP_OK if the check was performed successfully or an
XinZhangMS 0:f7f1f0d76dd6 147 * error code otherwise.
XinZhangMS 0:f7f1f0d76dd6 148 */
XinZhangMS 0:f7f1f0d76dd6 149 MOCKABLE_FUNCTION(, MAP_RESULT, Map_ContainsKey, MAP_HANDLE, handle, const char*, key, bool*, keyExists);
XinZhangMS 0:f7f1f0d76dd6 150
XinZhangMS 0:f7f1f0d76dd6 151 /**
XinZhangMS 0:f7f1f0d76dd6 152 * @brief This function returns @c true in @p valueExists if at
XinZhangMS 0:f7f1f0d76dd6 153 * least one <key,value> pair exists in the map where the entry's
XinZhangMS 0:f7f1f0d76dd6 154 * value is equal to the parameter @c value.
XinZhangMS 0:f7f1f0d76dd6 155 *
XinZhangMS 0:f7f1f0d76dd6 156 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 157 * @param value The value that the caller wants checked.
XinZhangMS 0:f7f1f0d76dd6 158 * @param valueExists The function writes @c true at the address pointed at
XinZhangMS 0:f7f1f0d76dd6 159 * by this parameter if the value exists in the map and
XinZhangMS 0:f7f1f0d76dd6 160 * @c false otherwise.
XinZhangMS 0:f7f1f0d76dd6 161 *
XinZhangMS 0:f7f1f0d76dd6 162 * @return Returns @c MAP_OK if the check was performed successfully or an
XinZhangMS 0:f7f1f0d76dd6 163 * error code otherwise.
XinZhangMS 0:f7f1f0d76dd6 164 */
XinZhangMS 0:f7f1f0d76dd6 165 MOCKABLE_FUNCTION(, MAP_RESULT, Map_ContainsValue, MAP_HANDLE, handle, const char*, value, bool*, valueExists);
XinZhangMS 0:f7f1f0d76dd6 166
XinZhangMS 0:f7f1f0d76dd6 167 /**
XinZhangMS 0:f7f1f0d76dd6 168 * @brief Retrieves the value of a stored key.
XinZhangMS 0:f7f1f0d76dd6 169 *
XinZhangMS 0:f7f1f0d76dd6 170 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 171 * @param key The key to be looked up in the map.
XinZhangMS 0:f7f1f0d76dd6 172 *
XinZhangMS 0:f7f1f0d76dd6 173 * @return Returns @c NULL in case the input arguments are @c NULL or if the
XinZhangMS 0:f7f1f0d76dd6 174 * requested key is not found in the map. Returns a pointer to the
XinZhangMS 0:f7f1f0d76dd6 175 * key's value otherwise.
XinZhangMS 0:f7f1f0d76dd6 176 */
XinZhangMS 0:f7f1f0d76dd6 177 MOCKABLE_FUNCTION(, const char*, Map_GetValueFromKey, MAP_HANDLE, handle, const char*, key);
XinZhangMS 0:f7f1f0d76dd6 178
XinZhangMS 0:f7f1f0d76dd6 179 /**
XinZhangMS 0:f7f1f0d76dd6 180 * @brief Retrieves the complete list of keys and values from the map
XinZhangMS 0:f7f1f0d76dd6 181 * in @p values and @p keys. Also writes the size of the list
XinZhangMS 0:f7f1f0d76dd6 182 * in @p count.
XinZhangMS 0:f7f1f0d76dd6 183 *
XinZhangMS 0:f7f1f0d76dd6 184 * @param handle The handle to an existing map.
XinZhangMS 0:f7f1f0d76dd6 185 * @param keys The location where the list of keys is to be written.
XinZhangMS 0:f7f1f0d76dd6 186 * @param values The location where the list of values is to be written.
XinZhangMS 0:f7f1f0d76dd6 187 * @param count The number of stored keys and values is written at the
XinZhangMS 0:f7f1f0d76dd6 188 * location indicated by this pointer.
XinZhangMS 0:f7f1f0d76dd6 189 *
XinZhangMS 0:f7f1f0d76dd6 190 * @return Returns @c MAP_OK if the keys and values are retrieved and written
XinZhangMS 0:f7f1f0d76dd6 191 * successfully or an error code otherwise.
XinZhangMS 0:f7f1f0d76dd6 192 */
XinZhangMS 0:f7f1f0d76dd6 193 MOCKABLE_FUNCTION(, MAP_RESULT, Map_GetInternals, MAP_HANDLE, handle, const char*const**, keys, const char*const**, values, size_t*, count);
XinZhangMS 0:f7f1f0d76dd6 194
XinZhangMS 0:f7f1f0d76dd6 195 /*this API creates a JSON object from the content of the map*/
XinZhangMS 0:f7f1f0d76dd6 196 MOCKABLE_FUNCTION(, STRING_HANDLE, Map_ToJSON, MAP_HANDLE, handle);
XinZhangMS 0:f7f1f0d76dd6 197
XinZhangMS 0:f7f1f0d76dd6 198 #ifdef __cplusplus
XinZhangMS 0:f7f1f0d76dd6 199 }
XinZhangMS 0:f7f1f0d76dd6 200 #endif
XinZhangMS 0:f7f1f0d76dd6 201
XinZhangMS 0:f7f1f0d76dd6 202 #endif /* MAP_H */