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[], int 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[], int *value) NONNULL USERESULT; 203 204 /** Commit criteria change and change parameters according to the configurations. 205 * Criterion do not have impact on the parameters value when changed, 206 * instead they are staged and only feed to the rule engine 207 * (who then impact parameter values according to the configuration) when 208 * committed with this function. 209 * 210 * @param[in] handle @see PfwHandler 211 * @return true on success and false on failure. 212 */ 213 CPARAMETER_EXPORT 214 bool pfwApplyConfigurations(const PfwHandler *handle) NONNULL USERESULT; 215 216 /////////////////////////////// 217 /////// Parameter access ////// 218 /////////////////////////////// 219 220 /** Handler to a pfw parameter. 221 * A PfwParameterHandler* is valid if: 222 * - it was created by pfwBindParameter 223 * - it has not been destroyed by pfwDestroyParameter 224 * - is not NULL 225 * - the pfwHandle used to created is still valid (ie. it must not outlive 226 * its parent pfw) 227 * A valid handle MUST be provided to all pfw parameter related method. 228 * Any created handle MUST be destroyed (with pfwDestroyParameter) before 229 * the PfwHandler that was used for its creation. 230 * @note Forward declaration to break header dependency. 231 */ 232 struct PfwParameterHandler_; 233 typedef struct PfwParameterHandler_ PfwParameterHandler; 234 235 /** Construct the handle to a parameter given its path. 236 * The PfwHandle MUST stay valid until PfwParameterHandler destruction. 237 * @return a PfwParameterHandler on success, NULL on error. 238 * @see pfwGetLastError for error detail. 239 */ 240 CPARAMETER_EXPORT 241 PfwParameterHandler *pfwBindParameter(PfwHandler *handle, const char path[]) NONNULL; 242 /** Destroy a parameter handle. Can not fail. */ 243 CPARAMETER_EXPORT 244 void pfwUnbindParameter(PfwParameterHandler *handle) NONNULL; 245 246 /** Access the value of a previously bind int parameter. 247 * @param[in] handle Handler to a valid parameter. 248 * @param[in] value Non null pointer to an integer that will 249 * hold the parameter value on success, undefined otherwise. 250 * return true of success, false on failure. 251 */ 252 CPARAMETER_EXPORT 253 bool pfwGetIntParameter(const PfwParameterHandler *handle, int32_t *value) NONNULL USERESULT; 254 255 /** Set the value of a previously bind int parameter. 256 * @param[in] handle Handler to a valid parameter. 257 * @param[in] value The parameter value to set. 258 * return true of success, false on failure. 259 */ 260 CPARAMETER_EXPORT 261 bool pfwSetIntParameter(PfwParameterHandler *handle, int32_t value) NONNULL USERESULT; 262 263 /** Access the value of a previously bind string parameter. 264 * @param[in] handle Handler to a valid parameter. 265 * @param[out] value Non null pointer on a string. 266 * Will point on the parameter value string on success, 267 * NULL on failure. 268 * The callee MUST free the returned string using pfwFree after use. 269 * @return true on success, false on failure. 270 */ 271 CPARAMETER_EXPORT 272 bool pfwGetStringParameter(const PfwParameterHandler *handle, char *value[]) NONNULL; 273 274 /** Set the value of a previously bind string parameter. 275 * @param[in] handle Handler to a valid parameter 276 * @param[in] value Non null pointer to a null terminated string to set. 277 */ 278 CPARAMETER_EXPORT 279 bool pfwSetStringParameter(PfwParameterHandler *handle, const char value[]) NONNULL USERESULT; 280 281 /** Frees the memory space pointed to by ptr, 282 * which must have been returned by a previous call to the pfw. 283 * 284 * @param[in] ptr pointer to the memory to free. 285 * @see man 3 free for usage. 286 * @note Wrapper around the standard free to avoid problems 287 * in case of a different pfw and client allocator. 288 */ 289 CPARAMETER_EXPORT 290 void pfwFree(void *ptr); 291 292 #undef NONNULL 293 #undef NONNULL_ 294 #undef USERESULT 295 296 #ifdef __cplusplus 297 } 298 #endif 299