bindings/c/ParameterFramework.h

/** @copyright
  * Copyright (c) 2015, Intel Corporation
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification,
  * are permitted provided that the following conditions are met:
  *
  * 1. Redistributions of source code must retain the above copyright notice, this
  * list of conditions and the following disclaimer.
  *
  * 2. Redistributions in binary form must reproduce the above copyright notice,
  * this list of conditions and the following disclaimer in the documentation and/or
  * other materials provided with the distribution.
  *
  * 3. Neither the name of the copyright holder nor the names of its contributors
  * may be used to endorse or promote products derived from this software without
  * specific prior written permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */

/** @file Simplified parameter framework C API.
  *       This API does not target a perfect one/one mapping with the c++ one,
  *       but rather aim ease of use and type safety (as far as possible in c).
  *       All function are reentrant and function call on a pfw (PfwHandle)
  *       does not impact any other pfw.
  *       Ie. There is no shared resources between pfw instances.
  */

#pragma once

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

/** Lots of function in this API require non null pointer parameter.
  * Such arguments are marked NONNULL.
  */
#define NONNULL  __attribute__((nonnull))
#define NONNULL_(...)  __attribute__((nonnull (__VA_ARGS__)))
#define USERESULT __attribute__((warn_unused_result))

/** Private handle to a parameter framework.
  * A PfwHandler* is valid if:
  *  - it was created by pfwCreate
  *  - it has not been destroyed by pfwDestroyParameter
  *  - is not NULL
  * A valid handle MUST be provided to all pfw related method.
  * A valid handler MUST be destroyed with pfwDestroy before programme
  * termination.
  * @note Forward declaration to break header dependency.
 */
struct PfwHandler_;
/** Typedef for use ease. @see PfwHandler_. */
typedef struct PfwHandler_ PfwHandler;

///////////////////////////////
///////////// Log /////////////
///////////////////////////////
/** Pfw log level for the callback. */
typedef enum {
    pfwLogInfo = 55, //< Random value to avoid unfortunate mismatch.
    pfwLogWarning
} PfwLogLevel;

/** Type of the parameter framework log callback.
  * @param userCtx[in] Arbitrary context provided during callback registration.
  * @param level[in] Log level of the log line.
  * @param logLine[in] Log line (without end line control character like '\n')
  *                    to be logged. The pointer is invalidate after function
  *                    return or if any pfw function is called.
  */
typedef void PfwLogCb(void *userCtx, PfwLogLevel level, const char *logLine);

/** Logger containing a callback method and its context. */
typedef struct {
    /** User defined arbitrary value that will be provided to all logCb call. */
    void *userCtx;
    /** Callback that will be called.
      * If NULL nothing will be logged.
      */
    PfwLogCb *logCb;
} PfwLogger;

///////////////////////////////
///////////// Core ////////////
///////////////////////////////

/** Structure of a parameter framework criterion. */
typedef struct {
    /** Name of the criterion in the pfw configuration rules. */
    const char *name; //< Must not be null.
    bool inclusive; //< True if the criterion is inclusive, false if exclusive.
    /** Null terminated list of criterion value names.
      * @example { "Red", "Green", "Blue", NULL }
      *
      * For an exclusive criterion, the list must not contain more elements then
      *                             INT_MAX.
      * For an inclusive criterion, the list must not contain more elements then
      *                             sizeof(int) * BIT_CHAR - 1.
      *                             Ie: (int)1 << n must *not* overflow (UB),
      *                                 were n is the number of element in the
      *                                 list. @see pfwSetCriterion
      */
    const char **values; //< Must not be null.
} PfwCriterion;


/** Create a parameter framework instance.
  * Can not fail except for memory allocation.
  */
PfwHandler *pfwCreate() USERESULT;

/** Destroy a parameter framework. Can not fail. */
void pfwDestroy(PfwHandler *handle) NONNULL;

/** Start a parameter framework.
  * @param handle[in] @see PfwHandler
  * @param configPath[in] Path to the file containing the pfw configuration.
  * @param criteria[in] An array of PfwCriterion.
  * @param criterionNb[in] The number of PfwCriterion in criteria.
  * @param logger[in] the logger to use for all operation.
  *                   If NULL, log infos to standard output and
  *                                errors to standard error.
  * @return true on success, false on failure.
  */
bool pfwStart(PfwHandler *handle, const char *configPath,
              const PfwCriterion criteria[], size_t criterionNb,
              const PfwLogger *loggger) NONNULL_(1, 2, 3) USERESULT;

/** @return a string describing the last call result.
  * If the last pfw function call succeeded, return an empty string.
  * If the last pfw function call failed, return a message explaining the error cause.
  * The return pointer is invalidated if any pfw method is called on the SAME
  * PfwHandle.
  *
  * Each PfwHandle own it's last error message. It is not static nor TLS.
  * As a result, calling a pfw function with a NULL PfwHandler will result in a
  * failure WITHOUT updating the last error.
  */
const char *pfwGetLastError(const PfwHandler *handle) NONNULL;

/** Set a criterion value given its name and value.
  * @param handle[in] @see PfwHandler
  * @param name[in] The name of the criterion that need to be changed.
  * @param value If the criterion is exclusive, the index of the new value.
  *              If the criterion is inclusive, a bit field where each bit
  *              correspond to the value index.
  * For an inclusive criterion defined as such: { "Red", "Green", "Blue", NULL }
  * to set the value Green and Blue, value has to be 1<<1 | 1<<2 = 0b110 = 6.
  * For an exclusive criterion defined as such: { "Car", "Boat", "Plane", NULL }
  * to set the value Plane, value has to be 2.
  *
  * Criterion change do not have impact on the parameters value
  * (no configuration applied) until the changes are committed using pfwApplyConfigurations.
  *
  * @return true on success and false on failure.
  */
bool pfwSetCriterion(PfwHandler *handle, const char name[], int value) NONNULL USERESULT;
/** Get a criterion value given its name.
  * Same usage as pfwSetCriterion except that value is an out param.
  * Get criterion will return the last value setted with pfwSetCriterion independantly of pfwCommitCritenio.
  */
bool pfwGetCriterion(const PfwHandler *handle, const char name[], int *value) NONNULL USERESULT;

/** Commit criteria change and change parameters according to the configurations.
  * Criterion do not have impact on the parameters value when changed,
  * instead they are staged and only feed to the rule engine
  * (who then impact parameter values according to the configuration) when
  * committed with this function.
  *
  * @param handle[in] @see PfwHandler
  * @return true on success and false on failure.
  */
bool pfwApplyConfigurations(const PfwHandler *handle) NONNULL USERESULT;

///////////////////////////////
/////// Parameter access //////
///////////////////////////////

/** Handler to a pfw parameter.
  * A PfwParameterHandler* is valid if:
  *  - it was created by pfwBindParameter
  *  - it has not been destroyed by pfwDestroyParameter
  *  - is not NULL
  *  - the pfwHandle used to created is still valid (ie. it must not outlive
  *    its parent pfw)
  * A valid handle MUST be provided to all pfw parameter related method.
  * Any created handle MUST be destroyed (with pfwDestroyParameter) before
  * the PfwHandler that was used for its creation.
  * @note Forward declaration to break header dependency.
  */
struct PfwParameterHandler_;
typedef struct PfwParameterHandler_ PfwParameterHandler;

/** Construct the handle to a parameter given its path.
  * The PfwHandle MUST stay valid until PfwParameterHandler destruction.
  * @return a PfwParameterHandler on success, NULL on error.
  *         @see pfwGetLastError for error detail.
  */
PfwParameterHandler *pfwBindParameter(PfwHandler *handle, const char path[]) NONNULL;
/** Destroy a parameter handle. Can not fail. */
void pfwUnbindParameter(PfwParameterHandler *handle) NONNULL;

/** Access the value of a previously bind int parameter.
  * @param handle[in] Handler to a valid parameter.
  * @param value[in] Non null pointer to an integer that will
  *        hold the parameter value on success, undefined otherwise.
  * return true of success, false on failure.
  */
bool pfwGetIntParameter(const PfwParameterHandler *handle, int32_t *value ) NONNULL USERESULT;

/** Set the value of a previously bind int parameter.
  * @param handle[in] Handler to a valid parameter.
  * @param value[in] The parameter value to set.
  * return true of success, false on failure.
  */
bool pfwSetIntParameter(PfwParameterHandler *handle, int32_t value) NONNULL USERESULT;

/** Access the value of a previously bind string parameter.
  * @param handle[in] Handler to a valid parameter.
  * @param value[out] Non null pointer on a string.
  *                   Will point on the parameter value string on success,
  *                   NULL on failure.
  *                   The callee MUST free the returned string using pfwFree after use.
  * @return true on success, false on failure.
  */
bool pfwGetStringParameter(const PfwParameterHandler *handle, const char *value[]) NONNULL;

/** Set the value of a previously bind string parameter.
  * @param handle[in] Handler to a valid parameter
  * @param value[in] Non null pointer to a null terminated string to set.
  */
bool pfwSetStringParameter(PfwParameterHandler *handle, const char value[]) NONNULL USERESULT;

/** Frees the memory space pointed to by ptr,
  *  which must have been returned by a previous call to the pfw.
  *
  * @param ptr[in] pointer to the memory to free.
  * @see man 3 free for usage.
  * @note Wrapper around the standard free to avoid problems
  *       in case of a different pfw and client allocator.
  */
void pfwFree(void *ptr);

#undef NONNULL
#undef NONNULL_
#undef USERESULT

#ifdef __cplusplus
}
#endif