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