1 /** @copyright 2 * Copyright (c) 2015, Intel Corporation 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without modification, 6 * are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright notice, 12 * this list of conditions and the following disclaimer in the documentation and/or 13 * other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its contributors 16 * may be used to endorse or promote products derived from this software without 17 * specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 31 /** @file 32 * 33 * Simplified parameter framework C API. This API does not target a perfect 34 * one/one mapping with the c++ one, but rather aim ease of use and type safety 35 * (as far as possible in c). All function are reentrant and function call on 36 * a pfw (PfwHandle) does not impact any other pfw. Ie. There is no shared 37 * resources between pfw instances. 38 */ 39 40 #pragma once 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 #include "cparameter_export.h" 47 48 #include <stdbool.h> 49 #include <stdint.h> 50 #include <stddef.h> 51 52 /** Lots of function in this API require non null pointer parameter. 53 * Such arguments are marked NONNULL. 54 */ 55 #if defined(__clang__) || defined(__GNUC__) 56 #define NONNULL __attribute__((nonnull)) 57 #define NONNULL_(...) __attribute__((nonnull(__VA_ARGS__))) 58 #define USERESULT __attribute__((warn_unused_result)) 59 #elif defined(_MSC_VER) 60 // In visual studio's cl there is no 61 // equivalent of nonnull 62 #define NONNULL 63 #define NONNULL_(...) 64 #define USERESULT _Check_return_ 65 #else 66 #error "Unknown compilator" 67 #endif 68 69 /** Private handle to a parameter framework. 70 * A PfwHandler* is valid if: 71 * - it was created by pfwCreate 72 * - it has not been destroyed by pfwDestroyParameter 73 * - is not NULL 74 * A valid handle MUST be provided to all pfw related method. 75 * A valid handler MUST be destroyed with pfwDestroy before programme 76 * termination. 77 * @note Forward declaration to break header dependency. 78 */ 79 struct PfwHandler_; 80 /** Typedef for use ease. @see PfwHandler_. */ 81 typedef struct PfwHandler_ PfwHandler; 82 83 /////////////////////////////// 84 ///////////// Log ///////////// 85 /////////////////////////////// 86 /** Pfw log level for the callback. */ 87 typedef enum { 88 pfwLogInfo = 55, //< Random value to avoid unfortunate mismatch. 89 pfwLogWarning 90 } PfwLogLevel; 91 92 /** Type of the parameter framework log callback. 93 * @param[in] userCtx Arbitrary context provided during callback registration. 94 * @param[in] level Log level of the log line. 95 * @param[in] logLine Log line (without end line control character like '\n') 96 * to be logged. The pointer is invalidate after function 97 * return or if any pfw function is called. 98 */ 99 typedef void PfwLogCb(void *userCtx, PfwLogLevel level, const char *logLine); 100 101 /** Logger containing a callback method and its context. */ 102 typedef struct 103 { 104 /** User defined arbitrary value that will be provided to all logCb call. */ 105 void *userCtx; 106 /** Callback that will be called. 107 * If NULL nothing will be logged. 108 */ 109 PfwLogCb *logCb; 110 } PfwLogger; 111 112 /////////////////////////////// 113 ///////////// Core //////////// 114 /////////////////////////////// 115 116 /** Structure of a parameter framework criterion. */ 117 typedef struct 118 { 119 /** Name of the criterion in the pfw configuration rules. */ 120 const char *name; //< Must not be null. 121 bool inclusive; //< True if the criterion is inclusive, false if exclusive. 122 123 /** Null terminated list of criterion value names. 124 * 125 * Example: 126 * @verbatim 127 * { "Red", "Green", "Blue", NULL } 128 * @endverbatim 129 * 130 * For an exclusive criterion, the list must not contain more elements then 131 * INT_MAX. 132 * For an inclusive criterion, the list must not contain more elements then 133 * sizeof(int) * BIT_CHAR - 1. 134 * Ie: (int)1 << n must *not* overflow (UB), 135 * were n is the number of element in the 136 * list. @see pfwSetCriterion 137 */ 138 const char **values; //< Must not be null. 139 } PfwCriterion; 140 141 /** Create a parameter framework instance. 142 * Can not fail except for memory allocation. 143 */ 144 CPARAMETER_EXPORT 145 PfwHandler *pfwCreate() USERESULT; 146 147 /** Destroy a parameter framework. Can not fail. */ 148 CPARAMETER_EXPORT 149 void pfwDestroy(PfwHandler *handle) NONNULL; 150 151 /** Start a parameter framework. 152 * @param[in] handle @see PfwHandler 153 * @param[in] configPath Path to the file containing the pfw configuration. 154 * @param[in] criteria An array of PfwCriterion. 155 * @param[in] criterionNb The number of PfwCriterion in criteria. 156 * @param[in] logger the logger to use for all operation. 157 * If NULL, log infos to standard output and 158 * errors to standard error. 159 * @return true on success, false on failure. 160 */ 161 CPARAMETER_EXPORT 162 bool pfwStart(PfwHandler *handle, const char *configPath, const PfwCriterion criteria[], 163 size_t criterionNb, const PfwLogger *logger) NONNULL_(1, 2, 3) USERESULT; 164 165 /** @return a string describing the last call result. 166 * If the last pfw function call succeeded, return an empty string. 167 * If the last pfw function call failed, return a message explaining the error cause. 168 * The return pointer is invalidated if any pfw method is called on the SAME 169 * PfwHandle. 170 * 171 * Each PfwHandle own it's last error message. It is not static nor TLS. 172 * As a result, calling a pfw function with a NULL PfwHandler will result in a 173 * failure WITHOUT updating the last error. 174 */ 175 CPARAMETER_EXPORT 176 const char *pfwGetLastError(const PfwHandler *handle) NONNULL; 177 178 /** Set a criterion value given its name and value. 179 * @param[in] handle @see PfwHandler 180 * @param[in] name The name of the criterion that need to be changed. 181 * @param[in] value If the criterion is exclusive, the index of the new value. 182 * If the criterion is inclusive, a bit field where each bit 183 * correspond to the value index. 184 * For an inclusive criterion defined as such: { "Red", "Green", "Blue", NULL } 185 * to set the value Green and Blue, value has to be 1<<1 | 1<<2 = 0b110 = 6. 186 * For an exclusive criterion defined as such: { "Car", "Boat", "Plane", NULL } 187 * to set the value Plane, value has to be 2. 188 * 189 * Criterion change do not have impact on the parameters value 190 * (no configuration applied) until the changes are committed using pfwApplyConfigurations. 191 * 192 * @return true on success and false on failure. 193 */ 194 CPARAMETER_EXPORT 195 bool pfwSetCriterion(PfwHandler *handle, const char name[], uint64_t value) NONNULL USERESULT; 196 /** Get a criterion value given its name. 197 * Same usage as pfwSetCriterion except that value is an out param. 198 * Get criterion will return the last value setted with pfwSetCriterion independantly of 199 * pfwCommitCritenio. 200 */ 201 CPARAMETER_EXPORT 202 bool pfwGetCriterion(const PfwHandler *handle, const char name[], 203 uint64_t *value) NONNULL USERESULT; 204 205 /** Commit criteria change and change parameters according to the configurations. 206 * Criterion do not have impact on the parameters value when changed, 207 * instead they are staged and only feed to the rule engine 208 * (who then impact parameter values according to the configuration) when 209 * committed with this function. 210 * 211 * @param[in] handle @see PfwHandler 212 * @return true on success and false on failure. 213 */ 214 CPARAMETER_EXPORT 215 bool pfwApplyConfigurations(const PfwHandler *handle) NONNULL USERESULT; 216 217 /////////////////////////////// 218 /////// Parameter access ////// 219 /////////////////////////////// 220 221 /** Handler to a pfw parameter. 222 * A PfwParameterHandler* is valid if: 223 * - it was created by pfwBindParameter 224 * - it has not been destroyed by pfwDestroyParameter 225 * - is not NULL 226 * - the pfwHandle used to created is still valid (ie. it must not outlive 227 * its parent pfw) 228 * A valid handle MUST be provided to all pfw parameter related method. 229 * Any created handle MUST be destroyed (with pfwDestroyParameter) before 230 * the PfwHandler that was used for its creation. 231 * @note Forward declaration to break header dependency. 232 */ 233 struct PfwParameterHandler_; 234 typedef struct PfwParameterHandler_ PfwParameterHandler; 235 236 /** Construct the handle to a parameter given its path. 237 * The PfwHandle MUST stay valid until PfwParameterHandler destruction. 238 * @return a PfwParameterHandler on success, NULL on error. 239 * @see pfwGetLastError for error detail. 240 */ 241 CPARAMETER_EXPORT 242 PfwParameterHandler *pfwBindParameter(PfwHandler *handle, const char path[]) NONNULL; 243 /** Destroy a parameter handle. Can not fail. */ 244 CPARAMETER_EXPORT 245 void pfwUnbindParameter(PfwParameterHandler *handle) NONNULL; 246 247 /** Access the value of a previously bind int parameter. 248 * @param[in] handle Handler to a valid parameter. 249 * @param[in] value Non null pointer to an integer that will 250 * hold the parameter value on success, undefined otherwise. 251 * return true of success, false on failure. 252 */ 253 CPARAMETER_EXPORT 254 bool pfwGetIntParameter(const PfwParameterHandler *handle, int32_t *value) NONNULL USERESULT; 255 256 /** Set the value of a previously bind int parameter. 257 * @param[in] handle Handler to a valid parameter. 258 * @param[in] value The parameter value to set. 259 * return true of success, false on failure. 260 */ 261 CPARAMETER_EXPORT 262 bool pfwSetIntParameter(PfwParameterHandler *handle, int32_t value) NONNULL USERESULT; 263 264 /** Access the value of a previously bind string parameter. 265 * @param[in] handle Handler to a valid parameter. 266 * @param[out] value Non null pointer on a string. 267 * Will point on the parameter value string on success, 268 * NULL on failure. 269 * The callee MUST free the returned string using pfwFree after use. 270 * @return true on success, false on failure. 271 */ 272 CPARAMETER_EXPORT 273 bool pfwGetStringParameter(const PfwParameterHandler *handle, char *value[]) NONNULL; 274 275 /** Set the value of a previously bind string parameter. 276 * @param[in] handle Handler to a valid parameter 277 * @param[in] value Non null pointer to a null terminated string to set. 278 */ 279 CPARAMETER_EXPORT 280 bool pfwSetStringParameter(PfwParameterHandler *handle, const char value[]) NONNULL USERESULT; 281 282 /** Frees the memory space pointed to by ptr, 283 * which must have been returned by a previous call to the pfw. 284 * 285 * @param[in] ptr pointer to the memory to free. 286 * @see man 3 free for usage. 287 * @note Wrapper around the standard free to avoid problems 288 * in case of a different pfw and client allocator. 289 */ 290 CPARAMETER_EXPORT 291 void pfwFree(void *ptr); 292 293 #undef NONNULL 294 #undef NONNULL_ 295 #undef USERESULT 296 297 #ifdef __cplusplus 298 } 299 #endif 300