Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/inc/azure_c_shared_utility/constmap.h

raw
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 constmap.h
5 * @brief ConstMap is a module that implements a read-only dictionary
6 * of @c const char* keys to @c const char* values.
7 */
8
9 #ifndef CONSTMAP_H
10 #define CONSTMAP_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/crt_abstractions.h"
20 #include "azure_c_shared_utility/map.h"
21 #include "umock_c/umock_c_prod.h"
22
23 #ifdef __cplusplus
24 extern "C"
25 {
26 #endif
27
28 #define CONSTMAP_RESULT_VALUES \
29 CONSTMAP_OK, \
30 CONSTMAP_ERROR, \
31 CONSTMAP_INVALIDARG, \
32 CONSTMAP_KEYNOTFOUND
33
34 /** @brief Enumeration specifying the status of calls to various APIs in this
35 * module.
36 */
37 MU_DEFINE_ENUM(CONSTMAP_RESULT, CONSTMAP_RESULT_VALUES);
38
39 typedef struct CONSTMAP_HANDLE_DATA_TAG* CONSTMAP_HANDLE;
40
41
42 /**
43 * @brief Creates a new read-only map from a map handle.
44 *
45 * @param sourceMap The map from which we will populate key,value
46 * into the read-only map.
47 *
48 * @return A valid @c CONSTMAP_HANDLE or @c NULL in case an error occurs.
49 */
50 MOCKABLE_FUNCTION(, CONSTMAP_HANDLE, ConstMap_Create, MAP_HANDLE, sourceMap);
51
52 /**
53 * @brief Destroy a read-only map. Deallocate memory associated with handle.
54 * @param handle Handle to a read-only map.
55 */
56 MOCKABLE_FUNCTION(, void, ConstMap_Destroy, CONSTMAP_HANDLE, handle);
57
58 /**
59 * @brief Clone a read-only map from another read-only map.
60 * @param handle Handle to a read-only map.
61 * @return A valid @c CONSTMAP_HANDLE or @c NULL in case an error occurs.
62 */
63 MOCKABLE_FUNCTION(, CONSTMAP_HANDLE, ConstMap_Clone, CONSTMAP_HANDLE, handle);
64
65 /**
66 * @brief Create a map handle populated from the read-only map.
67 * @param handle Handle to a read-only map.
68 * @return A valid @c MAP_HANDLE or @c NULL in case an error occurs.
69 *
70 * The new MAP_HANDLE needs to be destroyed when it is no longer needed.
71 */
72 MOCKABLE_FUNCTION(, MAP_HANDLE, ConstMap_CloneWriteable, CONSTMAP_HANDLE, handle);
73
74 /**
75 * @brief This function returns a true if the map contains a key
76 * with the same value the parameter @p key.
77 *
78 * @param handle The handle to an existing map.
79 * @param key The key that the caller wants checked.
80 *
81 * @return The function returns @c true if the key exists
82 * in the map and @c false if key is not found or
83 * parameters are invalid.
84 */
85 MOCKABLE_FUNCTION(, bool, ConstMap_ContainsKey, CONSTMAP_HANDLE, handle, const char*, key);
86
87 /**
88 * @brief This function returns @c true if at least one <key,value> pair
89 * exists in the map where the entry's value is equal to the
90 * parameter @c value.
91 *
92 * @param handle The handle to an existing map.
93 * @param value The value that the caller wants checked.
94 *
95 * @return The function returns @c true if the value exists
96 * in the map and @c false if value is not found or
97 * parameters are invalid.
98 */
99 MOCKABLE_FUNCTION(, bool, ConstMap_ContainsValue, CONSTMAP_HANDLE, handle, const char*, value);
100
101 /**
102 * @brief Retrieves the value of a stored key.
103 *
104 * @param handle The handle to an existing map.
105 * @param key The key to be looked up in the map.
106 *
107 * @return Returns @c NULL in case the input arguments are @c NULL or if the
108 * requested key is not found in the map. Returns a pointer to the
109 * key's value otherwise.
110 */
111 MOCKABLE_FUNCTION(, const char*, ConstMap_GetValue, CONSTMAP_HANDLE, handle, const char*, key);
112
113 /**
114 * @brief Retrieves the complete list of keys and values from the map
115 * in @p values and @p keys. Also writes the size of the list
116 * in @p count.
117 *
118 * @param handle The handle to an existing map.
119 * @param keys The location where the list of keys is to be written.
120 * @param values The location where the list of values is to be written.
121 * @param count The number of stored keys and values is written at the
122 * location indicated by this pointer.
123 *
124 * @return Returns @c CONSTMAP_OK if the keys and values are retrieved
125 * and written successfully or an error code otherwise.
126 */
127 MOCKABLE_FUNCTION(, CONSTMAP_RESULT, ConstMap_GetInternals, CONSTMAP_HANDLE, handle, const char*const**, keys, const char*const**, values, size_t*, count);
128
129
130 #ifdef __cplusplus
131 }
132 #endif
133
134 #endif /* CONSTMAP_H */