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 */
|
---|