sdk_mapped_flags.h

00001 /*
00002  * Copyright (c) Nordic Semiconductor ASA
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  *   1. Redistributions of source code must retain the above copyright notice, this
00009  *   list of conditions and the following disclaimer.
00010  *
00011  *   2. Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  *   3. Neither the name of Nordic Semiconductor ASA nor the names of other
00016  *   contributors to this software may be used to endorse or promote products
00017  *   derived from this software without specific prior written permission.
00018  *
00019  *
00020  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00021  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00022  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00023  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00024  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00025  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00026  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00027  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00028  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  */
00032 
00033 #ifndef SDK_MAPPED_FLAGS_H__
00034 #define SDK_MAPPED_FLAGS_H__
00035 
00036 #include <stdint.h>
00037 #include <stdbool.h>
00038 #include "app_util.h "
00039 #include "compiler_abstraction.h"
00040 
00041 /**
00042  * @file
00043  * @defgroup sdk_mapped_flags Mapped flags
00044  * @ingroup app_common
00045  * @{
00046  * @brief Module for writing and reading flags that are associated
00047  *        with keys.
00048  *
00049  * @details The flags are represented as bits in a bitmap called a <i>flag collection</i>. The keys
00050  *          are uint16_t. Each flag collection contains all flags of the same type, one flag for
00051  *          each key.
00052  *
00053  *          The mapped flags module does not keep the flag states, nor the list of keys. These are
00054  *          provided in the API calls. A key's index in the key list determines which bit in the
00055  *          flag collection is associated with it. This module does not ever edit the key list, and
00056  *          does not edit flags except in function calls that take the flag collection as a pointer.
00057  *
00058  */
00059 
00060 #define SDK_MAPPED_FLAGS_N_KEYS          8       /**< The number of keys to keep flags for. This is also the number of flags in a flag collection. If changing this value, you might also need change the width of the sdk_mapped_flags_t type. */
00061 #define SDK_MAPPED_FLAGS_N_KEYS_PER_BYTE 8       /**< The number of flags that fit in one byte. */
00062 #define SDK_MAPPED_FLAGS_INVALID_INDEX   0xFFFF  /**< A flag index guaranteed to be invalid. */
00063 
00064 typedef uint8_t sdk_mapped_flags_t; /**< The bitmap to hold flags. Each flag is one bit, and each bit represents the flag state associated with one key. */
00065 
00066 
00067 // Test whether the flag collection type is large enough to hold all the flags. If this fails,
00068 // reduce SDK_MAPPED_FLAGS_N_KEYS or increase the size of sdk_mapped_flags_t.
00069 STATIC_ASSERT((
00070     sizeof(sdk_mapped_flags_t)*SDK_MAPPED_FLAGS_N_KEYS_PER_BYTE) >= SDK_MAPPED_FLAGS_N_KEYS);
00071 
00072 
00073 /**@brief Type used to present a subset of the registered keys.
00074  */
00075 typedef struct
00076 {
00077     uint32_t len;                                 /**< The length of the list. */
00078     uint16_t flag_keys[SDK_MAPPED_FLAGS_N_KEYS];  /**< The list of keys. */
00079 } sdk_mapped_flags_key_list_t;
00080 
00081 
00082 /**@brief Function for getting the first index at which the flag is true in the provided
00083  *        collection.
00084  *
00085  * @param[in]  flags   The flag collection to search for a flag set to true.
00086  *
00087  * @return  The first index that has its flag set to true. If none were found, the
00088  *          function returns @ref SDK_MAPPED_FLAGS_INVALID_INDEX.
00089  */
00090 uint16_t sdk_mapped_flags_first_key_index_get(sdk_mapped_flags_t flags);
00091 
00092 
00093 /**@brief Function for updating the state of a flag.
00094  *
00095  * @param[in]  p_keys   The list of associated keys (assumed to have a length of
00096  *                      @ref SDK_MAPPED_FLAGS_N_KEYS).
00097  * @param[out] p_flags  The flag collection to modify.
00098  * @param[in]  key      The key to modify the flag of.
00099  * @param[in]  value    The state to set the flag to.
00100  */
00101 void sdk_mapped_flags_update_by_key(uint16_t           * p_keys,
00102                                     sdk_mapped_flags_t * p_flags,
00103                                     uint16_t             key,
00104                                     bool                 value);
00105 
00106 
00107 /**@brief Function for updating the state of the same flag in multiple flag collections.
00108  *
00109  * @details The key and value are the same for all flag collections in the p_flags array.
00110  *
00111  * @param[in]  p_keys              The list of associated keys (assumed to have a length of
00112  *                                 @ref SDK_MAPPED_FLAGS_N_KEYS).
00113  * @param[out] p_flags             The flag collections to modify.
00114  * @param[out] n_flag_collections  The number of flag collections in p_flags.
00115  * @param[in]  key                 The key to modify the flag of.
00116  * @param[in]  value               The state to set the flag to.
00117  */
00118 void sdk_mapped_flags_bulk_update_by_key(uint16_t           * p_keys,
00119                                          sdk_mapped_flags_t * p_flags,
00120                                          uint32_t             n_flag_collections,
00121                                          uint16_t             key,
00122                                          bool                 value);
00123 
00124 
00125 /**@brief Function for getting the state of a specific flag.
00126  *
00127  * @param[in]  p_keys  The list of associated keys (assumed to have a length of
00128  *                     @ref SDK_MAPPED_FLAGS_N_KEYS).
00129  * @param[in]  flags   The flag collection to read from.
00130  * @param[in]  key     The key to get the flag for.
00131  *
00132  * @return  The state of the flag.
00133  */
00134 bool sdk_mapped_flags_get_by_key(uint16_t * p_keys, sdk_mapped_flags_t flags, uint16_t key);
00135 
00136 
00137 /**@brief Function for getting a list of all keys that have a specific flag set to true.
00138  *
00139  * @param[in]  p_keys  The list of associated keys (assumed to have a length of
00140  *                     @ref SDK_MAPPED_FLAGS_N_KEYS).
00141  * @param[in]  flags   The flag collection to search.
00142  *
00143  * @return  The list of keys.
00144  */
00145 sdk_mapped_flags_key_list_t sdk_mapped_flags_key_list_get(uint16_t           * p_keys,
00146                                                           sdk_mapped_flags_t   flags);
00147 
00148 
00149 /**@brief Function for getting the number of keys that have a specific flag set to true.
00150  *
00151  * @param[in]  flags  The flag collection to search.
00152  *
00153  * @return  The number of keys.
00154  */
00155 uint32_t sdk_mapped_flags_n_flags_set(sdk_mapped_flags_t flags);
00156 
00157 
00158 /**@brief Function for querying whether any flags in the collection are set.
00159  *
00160  * @param[in]  flags  The flag collection to query.
00161  *
00162  * @retval  true If one or more flags are set to true.
00163  * @retval  false Otherwise.
00164  */
00165 static __INLINE bool sdk_mapped_flags_any_set(sdk_mapped_flags_t flags)
00166 {
00167     return (flags != 0);
00168 }
00169 
00170 
00171 /** @} */
00172 
00173 #endif /* SDK_MAPPED_FLAGS_H__ */