map.h

00001 // Copyright (c) Microsoft. All rights reserved.
00002 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
00003 
00004 /** @file       map.h
00005 *   @brief      Map is a module that implements a dictionary of @c STRING_HANDLE
00006 *               keys to @c STRING_HANDLE values.
00007 */
00008 
00009 #ifndef MAP_H
00010 #define MAP_H
00011 
00012 #include "azure_c_shared_utility/macro_utils.h"
00013 #include "azure_c_shared_utility/strings.h"
00014 #include "azure_c_shared_utility/crt_abstractions.h"
00015 #include "azure_c_shared_utility/umock_c_prod.h"
00016 
00017 #ifdef __cplusplus
00018 #include <cstddef>
00019 extern "C"
00020 {
00021 #else
00022 #include <stddef.h>
00023 #endif
00024 
00025 #define MAP_RESULT_VALUES \
00026     MAP_OK, \
00027     MAP_ERROR, \
00028     MAP_INVALIDARG, \
00029     MAP_KEYEXISTS, \
00030     MAP_KEYNOTFOUND, \
00031     MAP_FILTER_REJECT
00032 
00033 /** @brief Enumeration specifying the status of calls to various APIs in this  
00034  *  module.
00035  */
00036 DEFINE_ENUM(MAP_RESULT, MAP_RESULT_VALUES);
00037 
00038 typedef struct MAP_HANDLE_DATA_TAG* MAP_HANDLE;
00039 
00040 typedef int (*MAP_FILTER_CALLBACK)(const char* mapProperty, const char* mapValue);
00041 
00042 /**
00043  * @brief   Creates a new, empty map.
00044  *
00045  * @param   mapFilterFunc   A callback function supplied by the caller that is
00046  *                          invoked during calls to ::Map_Add and
00047  *                          ::Map_AddOrUpdate to provide the caller an
00048  *                          opportunity to indicate whether the new entry or
00049  *                          the update to an existing entry can be made or not.
00050  *                          The callback function can request that the operation
00051  *                          be canceled by returning a non-zero value from the
00052  *                          callback.
00053  *
00054  * @return  A valid @c MAP_HANDLE or @c NULL in case an error occurs.
00055  */
00056 MOCKABLE_FUNCTION(, MAP_HANDLE, Map_Create, MAP_FILTER_CALLBACK, mapFilterFunc);
00057 
00058 /**
00059  * @brief   Release all resources associated with the map.
00060  *
00061  * @param   handle  The handle to an existing map.
00062  */
00063 MOCKABLE_FUNCTION(, void, Map_Destroy, MAP_HANDLE, handle);
00064 
00065 /**
00066  * @brief   Creates a copy of the map indicated by @p handle and returns a
00067  *          handle to it.
00068  *
00069  * @param   handle  The handle to an existing map.
00070  *
00071  * @return  A valid @c MAP_HANDLE to the cloned copy of the map or @c NULL
00072  *          in case an error occurs.
00073  */
00074 MOCKABLE_FUNCTION(, MAP_HANDLE, Map_Clone, MAP_HANDLE, handle);
00075 
00076 /**
00077  * @brief   Adds a key/value pair to the map.
00078  *
00079  * @param   handle  The handle to an existing map.
00080  * @param   key     The @c key to be used for this map entry.
00081  * @param   value   The @c value to be associated with @p key.
00082  *
00083  *          If a non-NULL pointer to a callback function was supplied
00084  *          via the @c mapFilterFunc parameter when ::Map_Create was
00085  *          called then that callback is invoked when a new entry is
00086  *          added and if the callback returns a non-zero value then
00087  *          the function cancels the add operation and returns
00088  *          @c MAP_FILTER_REJECT.
00089  * 
00090  * @return  If any of the input parameters are @c NULL then this function
00091  *          returns @c MAP_INVALID_ARG. If the key already exists in the
00092  *          map then @c MAP_KEYEXISTS is returned. If the filter function
00093  *          associated with the map rejects the entry then
00094  *          @c MAP_FILTER_REJECT is returned. In case an error occurs when
00095  *          the new key is added to the map the function returns @c MAP_ERROR.
00096  *          If everything goes well then @c MAP_OK is returned.
00097  */
00098 MOCKABLE_FUNCTION(, MAP_RESULT, Map_Add, MAP_HANDLE, handle, const char*, key, const char*, value);
00099 
00100 /**
00101  * @brief   Adds/updates a key/value pair to the map.
00102  *
00103  * @param   handle  The handle to an existing map.
00104  * @param   key     The @c key to be used for this map entry.
00105  * @param   value   The @c value to be associated with @p key.
00106  *
00107  *          This function behaves exactly like ::Map_Add except that if the key
00108  *          already exists in the map then it overwrites the value with the
00109  *          supplied value instead of returning an error. If a non-NULL pointer
00110  *          to a callback function was supplied via the @c mapFilterFunc parameter
00111  *          when ::Map_Create was called then that callback is invoked when a new
00112  *          entry is added or when an existing entry is updated and if the
00113  *          callback returns a non-zero value then the function cancels the
00114  *          add/update operation and returns @c MAP_FILTER_REJECT.
00115  * 
00116  * @return  If any of the input parameters are @c NULL then this function
00117  *          returns @c MAP_INVALID_ARG. If the filter function associated
00118  *          with the map rejects the entry then @c MAP_FILTER_REJECT is
00119  *          returned. In case an error occurs when the new key is
00120  *          added/updated in the map the function returns @c MAP_ERROR. If
00121  *          everything goes well then @c MAP_OK is returned.
00122  */
00123 MOCKABLE_FUNCTION(, MAP_RESULT, Map_AddOrUpdate, MAP_HANDLE, handle, const char*, key, const char*, value);
00124 
00125 /**
00126  * @brief   Removes a key and its associated value from the map.
00127  *
00128  * @param   handle  The handle to an existing map.
00129  * @param   key     The @c key of the item to be deleted.
00130  *
00131  * @return  Returns @c MAP_OK if the key was deleted successfully or an
00132  *          error code otherwise.
00133  */
00134 MOCKABLE_FUNCTION(, MAP_RESULT, Map_Delete, MAP_HANDLE, handle, const char*, key);
00135 
00136 /**
00137  * @brief   This function returns a boolean value in @p keyExists if the map
00138  *          contains a key with the same value the parameter @p key.
00139  *
00140  * @param   handle      The handle to an existing map.
00141  * @param   key         The key that the caller wants checked.
00142  * @param   keyExists   The function writes @c true at the address pointed at
00143  *                      by this parameter if the key exists in the map and
00144  *                      @c false otherwise.
00145  *
00146  * @return  Returns @c MAP_OK if the check was performed successfully or an
00147  *          error code otherwise.
00148  */
00149 MOCKABLE_FUNCTION(, MAP_RESULT, Map_ContainsKey, MAP_HANDLE, handle, const char*, key, bool*, keyExists);
00150 
00151 /**
00152  * @brief   This function returns @c true in @p valueExists if at
00153  *          least one <key,value> pair exists in the map where the entry's
00154  *          value is equal to the parameter @c value.
00155  *
00156  * @param   handle          The handle to an existing map.
00157  * @param   value           The value that the caller wants checked.
00158  * @param   valueExists     The function writes @c true at the address pointed at
00159  *                          by this parameter if the value exists in the map and
00160  *                          @c false otherwise.
00161  *
00162  * @return  Returns @c MAP_OK if the check was performed successfully or an
00163  *          error code otherwise.
00164  */
00165 MOCKABLE_FUNCTION(, MAP_RESULT, Map_ContainsValue, MAP_HANDLE, handle, const char*, value, bool*, valueExists);
00166 
00167 /**
00168  * @brief   Retrieves the value of a stored key.
00169  *
00170  * @param   handle  The handle to an existing map.
00171  * @param   key     The key to be looked up in the map.
00172  *
00173  * @return  Returns @c NULL in case the input arguments are @c NULL or if the
00174  *          requested key is not found in the map. Returns a pointer to the
00175  *          key's value otherwise.
00176  */
00177 MOCKABLE_FUNCTION(, const char*, Map_GetValueFromKey, MAP_HANDLE, handle, const char*, key);
00178 
00179 /**
00180  * @brief   Retrieves the complete list of keys and values from the map
00181  *          in @p values and @p keys. Also writes the size of the list
00182  *          in @p count.
00183  *
00184  * @param   handle      The handle to an existing map.
00185  * @param   keys        The location where the list of keys is to be written.
00186  * @param   values      The location where the list of values is to be written.
00187  * @param   count       The number of stored keys and values is written at the
00188  *                      location indicated by this pointer.
00189  *
00190  * @return  Returns @c MAP_OK if the keys and values are retrieved and written
00191  *          successfully or an error code otherwise.
00192  */
00193 MOCKABLE_FUNCTION(, MAP_RESULT, Map_GetInternals, MAP_HANDLE, handle, const char*const**, keys, const char*const**, values, size_t*, count);
00194 
00195 /*this API creates a JSON object from the content of the map*/
00196 MOCKABLE_FUNCTION(, STRING_HANDLE, Map_ToJSON, MAP_HANDLE, handle);
00197 
00198 #ifdef __cplusplus
00199 }
00200 #endif
00201 
00202 #endif /* MAP_H */