constmap.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       constmap.h
00005 *   @brief      ConstMap is a module that implements a read-only dictionary
00006 *           of @c const char* keys to @c const char* values.
00007 */
00008 
00009 #ifndef CONSTMAP_H
00010 #define CONSTMAP_H
00011 
00012 #ifdef __cplusplus
00013 #include <cstddef>
00014 extern "C"
00015 {
00016 #else
00017 #include <stddef.h>
00018 #endif
00019 
00020 
00021 #include "azure_c_shared_utility/macro_utils.h"
00022 #include "azure_c_shared_utility/crt_abstractions.h"
00023 #include "azure_c_shared_utility/map.h"
00024 #include "azure_c_shared_utility/umock_c_prod.h"
00025 
00026 #define CONSTMAP_RESULT_VALUES \
00027     CONSTMAP_OK, \
00028     CONSTMAP_ERROR, \
00029     CONSTMAP_INVALIDARG, \
00030     CONSTMAP_KEYNOTFOUND
00031 
00032 /** @brief Enumeration specifying the status of calls to various APIs in this  
00033  *  module.
00034  */ 
00035 DEFINE_ENUM(CONSTMAP_RESULT, CONSTMAP_RESULT_VALUES);
00036  
00037 typedef struct CONSTMAP_HANDLE_DATA_TAG* CONSTMAP_HANDLE;
00038  
00039 
00040 /**
00041  * @brief   Creates a new read-only map from a map handle.
00042  *
00043  * @param   sourceMap   The map from which we will populate key,value
00044  *                      into the read-only map.
00045  *
00046  * @return  A valid @c CONSTMAP_HANDLE or @c NULL in case an error occurs.
00047  */
00048 MOCKABLE_FUNCTION(, CONSTMAP_HANDLE, ConstMap_Create, MAP_HANDLE, sourceMap);
00049 
00050  /** 
00051   * @brief  Destroy a read-only map.  Deallocate memory associated with handle.
00052   * @param  handle      Handle to a read-only map.
00053   */
00054 MOCKABLE_FUNCTION(, void, ConstMap_Destroy, CONSTMAP_HANDLE, handle);
00055 
00056  /** 
00057   * @brief  Clone a read-only map from another read-only map. 
00058   * @param  handle      Handle to a read-only map.
00059   * @return A valid @c CONSTMAP_HANDLE or @c NULL in case an error occurs.
00060   */
00061 MOCKABLE_FUNCTION(, CONSTMAP_HANDLE, ConstMap_Clone, CONSTMAP_HANDLE, handle);
00062 
00063  /** 
00064   * @brief  Create a map handle populated from the read-only map.
00065   * @param  handle      Handle to a read-only map.
00066   * @return A valid @c MAP_HANDLE or @c NULL in case an error occurs.
00067   *  
00068   * The new MAP_HANDLE needs to be destroyed when it is no longer needed.
00069   */
00070 MOCKABLE_FUNCTION(, MAP_HANDLE, ConstMap_CloneWriteable, CONSTMAP_HANDLE, handle);
00071 
00072 /**
00073  * @brief   This function returns a true if the map contains a key 
00074  *          with the same value the parameter @p key.
00075  *
00076  * @param   handle      The handle to an existing map.
00077  * @param   key         The key that the caller wants checked.
00078  *
00079  * @return              The function returns @c true if the key exists 
00080  *                      in the map and @c false if key is not found or 
00081  *                      parameters are invalid.
00082  */
00083 MOCKABLE_FUNCTION(, bool, ConstMap_ContainsKey, CONSTMAP_HANDLE, handle, const char*, key);
00084 
00085 /**
00086  * @brief   This function returns @c true if at least one <key,value> pair 
00087  *          exists in the map where the entry's value is equal to the 
00088  *          parameter @c value.
00089  *
00090  * @param   handle          The handle to an existing map.
00091  * @param   value           The value that the caller wants checked.
00092  *
00093  * @return                  The function returns @c true if the value exists 
00094  *                          in the map and @c false if value is not found or 
00095  *                          parameters are invalid.
00096  */
00097 MOCKABLE_FUNCTION(, bool, ConstMap_ContainsValue, CONSTMAP_HANDLE, handle, const char*, value);
00098 
00099 /**
00100  * @brief   Retrieves the value of a stored key.
00101  *
00102  * @param   handle  The handle to an existing map.
00103  * @param   key     The key to be looked up in the map.
00104  *
00105  * @return  Returns @c NULL in case the input arguments are @c NULL or if the
00106  *          requested key is not found in the map. Returns a pointer to the
00107  *          key's value otherwise.
00108  */
00109 MOCKABLE_FUNCTION(, const char*, ConstMap_GetValue, CONSTMAP_HANDLE, handle, const char*, key);
00110  
00111  /**
00112  * @brief   Retrieves the complete list of keys and values from the map
00113  *          in @p values and @p keys. Also writes the size of the list
00114  *          in @p count.
00115  *
00116  * @param   handle      The handle to an existing map.
00117  * @param   keys        The location where the list of keys is to be written.
00118  * @param   values      The location where the list of values is to be written.
00119  * @param   count       The number of stored keys and values is written at the
00120  *                      location indicated by this pointer.
00121  *
00122  * @return  Returns @c CONSTMAP_OK if the keys and values are retrieved
00123  *                     and written successfully or an error code otherwise.
00124  */
00125 MOCKABLE_FUNCTION(, CONSTMAP_RESULT, ConstMap_GetInternals, CONSTMAP_HANDLE, handle, const char*const**, keys, const char*const**, values, size_t*, count);
00126 
00127 
00128 #ifdef __cplusplus
00129 }
00130 #endif
00131 
00132 #endif /* CONSTMAP_H */