C pfw bindings

The pfw can not currently be used from c code.

Add an c api. It 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).

Signed-off-by: Kevin Rocard <kevin.rocard@intel.com>

6 files changed, 1143 insertions, 0 deletions

diff --git a/.travis.yml b/.travis.yml
index 21a3c6a..4ec4a2c 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -15,6 +15,8 @@ install:
   - sudo apt-get install --yes swig cmake valgrind g++-4.8
   - sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.8 100
   - sudo update-alternatives --install /usr/bin/gcov gcov /usr/bin/gcov-4.8 100
+  - sudo wget --directory-prefix /usr/include/
+              https://raw.github.com/philsquared/Catch/master/single_include/catch.hpp
 
 # how to build
 script:
diff --git a/bindings/CMakeLists.txt b/bindings/CMakeLists.txt
index ba59221..446b52f 100644
--- a/bindings/CMakeLists.txt
+++ b/bindings/CMakeLists.txt
@@ -30,3 +30,8 @@ option(PYTHON_BINDINGS "Python library to use the pfw from python" ON)
 if(PYTHON_BINDINGS)
     add_subdirectory(python)
 endif()
+
+option(C_BINDINGS "Python library to use the pfw from python" ON)
+if(C_BINDINGS)
+    add_subdirectory(c)
+endif()
diff --git a/bindings/c/CMakeLists.txt b/bindings/c/CMakeLists.txt
new file mode 100644
index 0000000..b7eeff8
--- /dev/null
+++ b/bindings/c/CMakeLists.txt
@@ -0,0 +1,60 @@
+# 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.
+
+add_library(cparameter SHARED ParameterFramework.cpp)
+
+include_directories("${PROJECT_SOURCE_DIR}/parameter/include")
+
+install(FILES ParameterFramework.h
+        DESTINATION "include/parameter/c")
+
+target_link_libraries(cparameter parameter)
+
+if(BUILD_TESTING)
+    # Add catch unit test framework
+    # TODO Use gtest as it is the team recommendation
+    #      Unfortunately gtest is very hard to setup as not binary distributed
+    #      catch is only one header so it is very easy
+    # Catch can be downloaded from:
+    # https://raw.github.com/philsquared/Catch/master/single_include/catch.hpp
+    # Then append the download folder to the CMAKE_INCLUDE_PATH variable or
+    # copy it in a standard location (/usr/include on most linux distribution).
+    find_path(CATCH_HEADER catch.hpp)
+    include_directories(${CATCH_HEADER})
+
+    # Add unit test
+    add_executable(cparameterUnitTest Test.cpp)
+    # Do not warn about passing a null pointer for arguments marked as requiring
+    # a non-null value by the "nonnull" function attribute.
+    # This is done as the unit tests check that invalid api use result in
+    # proper failure.
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-nonnull")
+
+    target_link_libraries(cparameterUnitTest cparameter)
+    add_test(cparameterUnitTest cparameterUnitTest)
+endif()
diff --git a/bindings/c/ParameterFramework.cpp b/bindings/c/ParameterFramework.cpp
new file mode 100644
index 0000000..efc7d99
--- /dev/null
+++ b/bindings/c/ParameterFramework.cpp
@@ -0,0 +1,397 @@
+/*
+ * 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.
+ */
+
+#include "ParameterFramework.h"
+#include <ParameterMgrPlatformConnector.h>
+
+#include <iostream>
+#include <limits>
+#include <string>
+#include <map>
+
+#include <cassert>
+#include <cstring>
+#include <cstdlib>
+
+using std::string;
+
+/** Rename long pfw types to short ones in pfw namespace. */
+namespace pfw
+{
+    typedef ISelectionCriterionInterface Criterion;
+    typedef std::map<string, Criterion *> Criteria;
+    typedef CParameterMgrPlatformConnector Pfw;
+}
+
+/** Class to abstract the boolean+string status api. */
+class Status
+{
+public:
+    /** Fail without an instance of status. */
+    static bool failure() { return false; }
+    /** Fail with the given error msg. */
+    bool failure(const string &msg) { mMsg = msg; return false; }
+    /** Success (no error message). */
+    bool success() { mMsg.clear(); return true; }
+
+    /** Forward a status operation.
+      * @param success[in] the operaton status to forward
+      *                    or forward a previous failure if omitted
+      */
+    bool forward(bool success = false) {
+        if (success) { mMsg.clear(); }
+        return success;
+    }
+    /** Error message accessors.
+      *
+      * Pfw api requires to provide a reference to a string in order
+      * for it to log. This function provide a reference to a string that
+      * will be added to the error message on failure.
+      */
+    string &msg() { return mMsg; }
+private:
+    string mMsg;
+};
+
+///////////////////////////////
+///////////// Log /////////////
+///////////////////////////////
+
+/** Default log callback. Log to cout or cerr depending on level. */
+static void defaultLogCb(void *, PfwLogLevel level, const char *logLine) {
+    switch (level) {
+    case pfwLogInfo:
+        std::cout << logLine << std::endl;
+        break;
+    case pfwLogWarning:
+        std::cerr << logLine << std::endl;
+        break;
+    };
+}
+
+static PfwLogger defaultLogger = { NULL, &defaultLogCb };
+
+class LogWrapper : public CParameterMgrPlatformConnector::ILogger
+{
+public:
+    LogWrapper(const PfwLogger &logger) : mLogger(logger) {}
+    LogWrapper() : mLogger() {}
+    virtual ~LogWrapper() {}
+private:
+    virtual void log(bool bIsWarning, const string &strLog)
+    {
+        // A LogWrapper should NOT be register to the pfw (thus log called)
+        // if logCb is NULL.
+        assert(mLogger.logCb != NULL);
+        mLogger.logCb(mLogger.userCtx,
+                      bIsWarning ? pfwLogWarning : pfwLogInfo,
+                      strLog.c_str());
+    }
+    PfwLogger mLogger;
+};
+
+///////////////////////////////
+///////////// Core ////////////
+///////////////////////////////
+
+struct PfwHandler_
+{
+    void setLogger(const PfwLogger *logger);
+    bool createCriteria(const PfwCriterion criteria[], size_t criterionNb);
+
+    pfw::Criteria criteria;
+    pfw::Pfw *pfw;
+    /** Status of the last called function.
+      * Is mutable because even a const function can fail.
+      */
+    mutable Status lastStatus;
+private:
+    LogWrapper mLogger;
+};
+
+
+PfwHandler *pfwCreate()
+{
+    return new PfwHandler();
+}
+
+void pfwDestroy(PfwHandler *handle)
+{
+    if(handle != NULL and handle->pfw != NULL) {
+        delete handle->pfw;
+    }
+    delete handle;
+}
+
+void PfwHandler::setLogger(const PfwLogger *logger)
+{
+    if (logger != NULL and logger->logCb == NULL) {
+        return; // There is no callback, do not log => do not add a logger
+    }
+    mLogger = logger != NULL ? *logger : defaultLogger;
+    pfw->setLogger(&mLogger);
+}
+
+
+bool PfwHandler::createCriteria(const PfwCriterion criteriaArray[], size_t criterionNb)
+{
+    Status &status = lastStatus;
+    // Add criteria
+    for (size_t criterionIndex = 0; criterionIndex < criterionNb; ++criterionIndex) {
+        const PfwCriterion &criterion = criteriaArray[criterionIndex];
+        if (criterion.name == NULL) {
+            return status.failure("Criterion name is NULL");
+        }
+        if (criterion.values == NULL) {
+            return status.failure("Criterion values is NULL");
+        }
+        // Check that the criterion does not exist
+        if (criteria.find(criterion.name) != criteria.end()) {
+            return status.failure("Criterion \"" + string(criterion.name) +
+                                  "\" already exist");
+        }
+
+        // Create criterion type
+        ISelectionCriterionTypeInterface *type =
+            pfw->createSelectionCriterionType(criterion.inclusive);
+        assert(type != NULL);
+        // Add criterion values
+        for (size_t valueIndex = 0; criterion.values[valueIndex] != NULL; ++valueIndex) {
+            int value;
+            if (criterion.inclusive) {
+                // Check that (int)1 << valueIndex would not overflow (UB)
+                if(std::numeric_limits<int>::max() >> valueIndex == 0) {
+                    return status.failure("Too many values for criterion " +
+                                          string(criterion.name));
+                }
+                value = 1 << valueIndex;
+            } else {
+                value = valueIndex;
+            }
+            const char * valueName = criterion.values[valueIndex];
+            if(not type->addValuePair(value, valueName)) {
+                return status.failure("Could not add value " + string(valueName) +
+                                      " to criterion " + criterion.name);
+            }
+        }
+        // Create criterion and add it to the pfw
+        criteria[criterion.name] = pfw->createSelectionCriterion(criterion.name, type);
+    }
+    return status.success();
+}
+
+
+bool pfwStart(PfwHandler *handle, const char *configPath,
+              const PfwCriterion criteria[], size_t criterionNb,
+              const PfwLogger *logger)
+{
+    // Check that the api is correctly used
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->lastStatus;
+
+    if (handle->pfw != NULL) {
+        return status.failure("Can not start an already started parameter framework");
+    }
+    if (configPath == NULL) {
+        return status.failure("char *configPath is NULL, "
+                              "while starting the parameter framework");
+    }
+    if (criteria == NULL) {
+        return status.failure("char *criteria is NULL, "
+                              "while starting the parameter framework "
+                              "(config path is " + string(configPath) + ")");
+    }
+    // Create a pfw
+    handle->pfw = new CParameterMgrPlatformConnector(configPath);
+
+    handle->setLogger(logger);
+
+    if (not handle->createCriteria(criteria, criterionNb)) {
+        return status.failure();
+    }
+
+    return status.forward(handle->pfw->start(status.msg()));
+}
+
+const char *pfwGetLastError(const PfwHandler *handle)
+{
+    return handle == NULL ? NULL : handle->lastStatus.msg().c_str();
+}
+
+static pfw::Criterion *getCriterion(const pfw::Criteria &criteria,
+                                    const string &name)
+{
+    pfw::Criteria::const_iterator it = criteria.find(name);
+    return it == criteria.end() ? NULL : it->second;
+}
+
+bool pfwSetCriterion(PfwHandler *handle, const char name[], int value)
+{
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->lastStatus;
+    if (name == NULL) {
+        return status.failure("char *name of the criterion is NULL, "
+                              "while setting a criterion.");
+    }
+    if (handle->pfw == NULL) {
+        return status.failure("Can not set criterion \"" + string(name) +
+                              "\" as the parameter framework is not started.");
+    }
+    pfw::Criterion *criterion = getCriterion(handle->criteria, name);
+    if (criterion == NULL) {
+        return status.failure("Can not set criterion " + string(name) + " as does not exist");
+    }
+    criterion->setCriterionState(value);
+    return status.success();
+}
+bool pfwGetCriterion(const PfwHandler *handle, const char name[], int *value)
+{
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->lastStatus;
+    if (name == NULL) {
+        return status.failure("char *name of the criterion is NULL, "
+                              "while getting a criterion.");
+    }
+    if (handle->pfw == NULL) {
+        return status.failure("Can not get criterion \"" + string(name) +
+                              "\" as the parameter framework is not started.");
+    }
+    if (value == NULL) {
+        return status.failure("Can not get criterion \"" + string(name) +
+                              "\" as the out value is NULL.");
+    }
+    pfw::Criterion *criterion = getCriterion(handle->criteria, name);
+    if (criterion == NULL) {
+        return status.failure("Can not get criterion " + string(name) + " as it does not exist");
+    }
+    *value = criterion->getCriterionState();
+    return status.success();
+}
+
+bool pfwApplyConfigurations(const PfwHandler *handle)
+{
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->lastStatus;
+    if (handle->pfw == NULL) {
+        return status.failure("Can not commit criteria "
+                              "as the parameter framework is not started.");
+    }
+    handle->pfw->applyConfigurations();
+    return status.success();
+}
+
+///////////////////////////////
+/////// Parameter access //////
+///////////////////////////////
+
+struct PfwParameterHandler_
+{
+    PfwHandler &pfw;
+    CParameterHandle &parameter;
+};
+
+PfwParameterHandler *pfwBindParameter(PfwHandler *handle, const char path[])
+{
+    if (handle == NULL) { return NULL; }
+    Status &status = handle->lastStatus;
+    if (path == NULL) {
+        status.failure("Can not bind a parameter without its path");
+        return NULL;
+    }
+    if (handle->pfw == NULL) {
+        status.failure("The parameter framework is not started, "
+                       "while trying to bind parameter \"" + string(path) + "\")");
+        return NULL;
+    }
+
+    CParameterHandle *paramHandle;
+    paramHandle = handle->pfw->createParameterHandle(path, status.msg());
+    if (paramHandle == NULL) {
+        return NULL;
+    }
+
+    status.success();
+    PfwParameterHandler publicHandle = {*handle, *paramHandle};
+    return new PfwParameterHandler(publicHandle);
+}
+
+void pfwUnbindParameter(PfwParameterHandler *handle)
+{
+    if (handle == NULL) { return; }
+    delete &handle->parameter;
+    delete handle;
+}
+
+
+bool pfwGetIntParameter(const PfwParameterHandler *handle, int32_t *value)
+{
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->pfw.lastStatus;
+    if (value == NULL) {
+        return status.failure("int32_t *value is NULL, "
+                    "while trying to get parameter \"" +
+                    handle->parameter.getPath() + "\" value as int)");
+    }
+    return status.forward(handle->parameter.getAsSignedInteger(*value, status.msg()));
+}
+bool pfwSetIntParameter(PfwParameterHandler *handle, int32_t value)
+{
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->pfw.lastStatus;
+    return status.forward(handle->parameter.setAsSignedInteger(value, status.msg()));
+}
+
+bool pfwGetStringParameter(const PfwParameterHandler *handle, const char *value[])
+{
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->pfw.lastStatus;
+    if (value == NULL) {
+        return status.failure("char **value is NULL, "
+                    "while trying to get parameter \"" +
+                    handle->parameter.getPath() + "\" value as string)");
+    }
+    *value = NULL;
+    string retValue;
+    bool success = handle->parameter.getAsString(retValue, status.msg());
+    if (not success) { return status.forward(); }
+
+    *value = strdup(retValue.c_str());
+    return status.success();
+}
+
+bool pfwSetStringParameter(PfwParameterHandler *handle, const char value[])
+{
+    if (handle == NULL) { return Status::failure(); }
+    Status &status = handle->pfw.lastStatus;
+    return status.forward(handle->parameter.setAsString(value, status.msg()));
+}
+
+void pfwFree(void *ptr) { std::free(ptr); }
+
diff --git a/bindings/c/ParameterFramework.h b/bindings/c/ParameterFramework.h
new file mode 100644
index 0000000..20cc820
--- /dev/null
+++ b/bindings/c/ParameterFramework.h
@@ -0,0 +1,265 @@
+/** @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
diff --git a/bindings/c/Test.cpp b/bindings/c/Test.cpp
new file mode 100644
index 0000000..c450e60
--- /dev/null
+++ b/bindings/c/Test.cpp
@@ -0,0 +1,414 @@
+/*
+ * 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.
+ */
+
+#include "ParameterFramework.h"
+
+#define CATCH_CONFIG_MAIN  // This tells Catch to provide a main()
+#include <catch.hpp>
+
+#include <string>
+#include <memory>
+#include <vector>
+
+#include <cstring>
+#include <cerrno>
+#include <climits>
+extern "C"
+{
+#include <unistd.h>
+}
+
+struct Test
+{
+    /** @return true if str is empty. */
+    bool empty(const char *str)
+    {
+        REQUIRE(str != NULL);
+        return *str == '\0';
+    }
+
+    void REQUIRE_FAILURE(bool success)
+    {
+        THEN("It should be an error") {
+            INFO("Previous pfw log: \n" + logLines);
+            CAPTURE(pfwGetLastError(pfw));
+            CHECK(not success);
+            CHECK(not empty(pfwGetLastError(pfw)));
+        }
+    }
+
+    void REQUIRE_SUCCESS(bool success)
+    {
+        THEN("It should be a success") {
+            INFO("Previous pfw log: \n" + logLines);
+            CAPTURE(pfwGetLastError(pfw));
+            CHECK(success);
+            CHECK(empty(pfwGetLastError(pfw)));
+        }
+    }
+
+    /** Class to create a temporary file */
+    class TmpFile
+    {
+    public:
+        TmpFile(const std::string &content) {
+            char tmpName[] = "./tmpPfwUnitTestXXXXXX";
+            mFd = mkstemp(tmpName);
+            CAPTURE(errno);
+            REQUIRE(mFd != -1);
+            mPath = tmpName;
+            write(mFd, content.c_str(), content.length());
+        }
+        ~TmpFile() {
+            CHECK(close(mFd) != -1);
+            unlink(mPath.c_str());
+        }
+        operator const char *() const { return mPath.c_str(); }
+        const std::string &path() const { return mPath; }
+    private:
+        std::string mPath;
+        int mFd;
+    };
+
+    /** Log in logLines. */
+    static void logCb(void *voidLogLines, PfwLogLevel level, const char *logLine)
+    {
+        std::string &logLines = *reinterpret_cast<std::string *>(voidLogLines);
+        switch(level) {
+        case pfwLogWarning:
+            logLines += "Warning: ";
+            break;
+        case pfwLogInfo:
+            logLines += "Info: ";
+        }
+        logLines += logLine;
+        logLines += '\n';
+    }
+
+    /** Log buffer, will only be display in case of failure */
+    std::string logLines;
+
+    /** Pfw handler used in the tests. */
+    PfwHandler *pfw;
+
+};
+
+TEST_CASE_METHOD(Test, "Parameter-framework c api use") {
+    // Create criteria
+    const char *letterList[] = {"a", "b", "c", NULL};
+    const char *numberList[] = {"1", "2", "3", NULL};
+    const PfwCriterion criteria[] = {
+        {"inclusiveCrit", true, letterList},
+        {"exclusiveCrit", false, numberList},
+    };
+    size_t criterionNb = sizeof(criteria)/sizeof(criteria[0]);
+    PfwLogger logger = {&logLines, logCb};
+
+    // Create valid pfw config file
+    const char *intParameterPath = "/test/system/integer";
+    const char *stringParameterPath = "/test/system/string";
+    TmpFile system("<?xml version='1.0' encoding='UTF-8'?>\
+        <Subsystem Name='system' Type='Virtual' Endianness='Little'>\
+            <ComponentLibrary/>\
+            <InstanceDefinition>\
+                <IntegerParameter Name='integer' Size='32' Signed='true' Max='100'/>\
+                <StringParameter Name='string' MaxLength='9'/>\
+            </InstanceDefinition>\
+        </Subsystem>");
+    TmpFile libraries("<?xml version='1.0' encoding='UTF-8'?>\
+        <SystemClass Name='test'>\
+            <SubsystemInclude Path='" + system.path() + "'/>\
+        </SystemClass>");
+    TmpFile config("<?xml version='1.0' encoding='UTF-8'?>\
+        <ParameterFrameworkConfiguration\
+            SystemClassName='test' TuningAllowed='false'>\
+            <SubsystemPlugins/>\
+            <StructureDescriptionFileLocation Path='" + libraries.path() + "'/>\
+        </ParameterFrameworkConfiguration>");
+
+    GIVEN("A created parameter framework") {
+        pfw = pfwCreate();
+        REQUIRE(pfw != NULL);
+
+        THEN("Error message should be empty") {
+            CHECK(empty(pfwGetLastError(pfw)));
+        }
+
+        WHEN("The pfw is started without an handler") {
+            CHECK(not pfwStart(NULL, config, criteria, criterionNb, &logger));
+        }
+        WHEN("The pfw is started without a config path") {
+            REQUIRE_FAILURE(pfwStart(pfw, NULL, criteria, criterionNb, &logger));
+        }
+        WHEN("The pfw is started without an existent file") {
+            REQUIRE_FAILURE(pfwStart(pfw, "/doNotExist", criteria, criterionNb, &logger));
+        }
+
+        WHEN("The pfw is started without a criteria list") {
+            REQUIRE_FAILURE(pfwStart(pfw, config, NULL, criterionNb, &logger));
+        }
+        WHEN("The pfw is started with duplicated criterion value") {
+            const PfwCriterion duplicatedCriteria[] = {
+                {"duplicated name", true, letterList},
+                {"duplicated name", false, numberList},
+            };
+            REQUIRE_FAILURE(pfwStart(pfw, config, duplicatedCriteria, 2, &logger));
+        }
+        WHEN("The pfw is started with duplicated criterion value state") {
+            const char * values[] = {"a", "a", NULL};
+            const PfwCriterion duplicatedCriteria[] = {{"name", true, values}};
+
+            WHEN("Using test logger") {
+                REQUIRE_FAILURE(pfwStart(pfw, config, duplicatedCriteria, 1, &logger));
+            }
+            WHEN("Using default logger") {
+                // Test coverage of default logger warning
+                REQUIRE_FAILURE(pfwStart(pfw, config, duplicatedCriteria, 1, NULL));
+            }
+        }
+        WHEN("The pfw is started with NULL name criterion") {
+            const PfwCriterion duplicatedCriteria[] = {{NULL, true, letterList}};
+            REQUIRE_FAILURE(pfwStart(pfw, config, duplicatedCriteria, 1, &logger));
+        }
+        WHEN("The pfw is started with NULL criterion state list") {
+            const PfwCriterion duplicatedCriteria[] = {{"name", true, NULL}};
+            REQUIRE_FAILURE(pfwStart(pfw, config, duplicatedCriteria, 1, &logger));
+        }
+        GIVEN("A criteria with lots of values")
+        {
+            // Build a criterion with as many value as there is bits in int.
+            std::vector<char> names(sizeof(int) * CHAR_BIT + 1, 'a');
+            names.back() = '\0';
+            std::vector<const char *> values(names.size());
+            for(size_t i = 0; i < values.size(); ++i) {
+                values[i] = &names[i];
+            }
+            values.back() = NULL;
+            /* The pfw c api requires criterion values to be a NULL terminated
+             * array of string. Each string is a pointer to a NULL terminated
+             * array of char. The pfw requires each string to be different
+             * from all others, ie strcmp(values[i], values[j]) != 0 for any
+             * i j.
+             *
+             * In order to generate easily an array of different strings,
+             * instantiate one string (names) big enough
+             * (@see PfwCriterion::values).
+             * Then instantiate an array of pointer (values),
+             * each pointing to a different position in the previously
+             * created string.
+             *
+             * Representation of the names and values vectors.
+             *
+             * n = number of bit in an int
+             *            <--- n+1 elements --->
+             * names    = |a|a|a|a|...|a|a|a|\0|
+             *             ^ ^             ^
+             * values[0] = ´ |             |
+             * values[1] = --´             |
+             * ...                         |
+             * values[n - 1] =  -----------´
+             * values[n] = NULL
+             *
+             */
+            const PfwCriterion duplicatedCriteria[] = {{"name", true, &values[0]}};
+
+            WHEN("The pfw is started with a too long criterion state list") {
+                REQUIRE_FAILURE(pfwStart(pfw, config, duplicatedCriteria, 1, &logger));
+            }
+            WHEN("The pfw is started with max length criterion state list") {
+                values[values.size() - 2] = NULL; // Hide last value
+                REQUIRE_SUCCESS(pfwStart(pfw, config, duplicatedCriteria, 1, &logger));
+            }
+        }
+
+        WHEN("The pfw is started with zero criteria") {
+            REQUIRE_SUCCESS(pfwStart(pfw, config, criteria, 0, &logger));
+        }
+
+        WHEN("The pfw is started twice a pfw") {
+            REQUIRE_SUCCESS(pfwStart(pfw, config, criteria, criterionNb, &logger));
+            REQUIRE_FAILURE(pfwStart(pfw, config, criteria, criterionNb, &logger));
+        }
+
+        WHEN("The pfw is started without a logger callback") {
+            PfwLogger noLog = { NULL, NULL };
+            REQUIRE_SUCCESS(pfwStart(pfw, config, criteria, criterionNb, &noLog));
+        }
+        WHEN("The pfw is started with default logger") {
+            REQUIRE_SUCCESS(pfwStart(pfw, config, criteria, criterionNb, NULL));
+        }
+
+        WHEN("Get criterion of a stopped pfw") {
+            int value;
+            REQUIRE_FAILURE(pfwGetCriterion(pfw, criteria[0].name, &value));
+        }
+        WHEN("Set criterion of a stopped pfw") {
+            REQUIRE_FAILURE(pfwSetCriterion(pfw, criteria[0].name, 1));
+        }
+        WHEN("Commit criteria of a stopped pfw") {
+            REQUIRE_FAILURE(pfwApplyConfigurations(pfw));
+        }
+
+        WHEN("Bind parameter with a stopped pfw") {
+            REQUIRE(pfwBindParameter(pfw, intParameterPath) == NULL);
+        }
+
+        WHEN("The pfw is started correctly")
+        {
+            REQUIRE_SUCCESS(pfwStart(pfw, config, criteria, criterionNb, &logger));
+            int value;
+
+            WHEN("Get criterion without an handle") {
+                REQUIRE(not pfwGetCriterion(NULL, criteria[0].name, &value));
+            }
+            WHEN("Get criterion without a name") {
+                REQUIRE_FAILURE(pfwGetCriterion(pfw, NULL, &value));
+            }
+            WHEN("Get criterion without an output value") {
+                REQUIRE_FAILURE(pfwGetCriterion(pfw, criteria[0].name, NULL));
+            }
+            WHEN("Get not existing criterion") {
+                REQUIRE_FAILURE(pfwGetCriterion(pfw, "Do not exist", &value));
+            }
+            THEN("All criterion should value 0") {
+                for(size_t i = 0; i < criterionNb; ++i) {
+                    const char *criterionName = criteria[i].name;
+                    CAPTURE(criterionName);
+                    REQUIRE_SUCCESS(pfwGetCriterion(pfw, criterionName, &value));
+                    REQUIRE(value == 0);
+                }
+            }
+
+            WHEN("Set criterion without an handle") {
+                REQUIRE(not pfwSetCriterion(NULL, criteria[0].name, 1));
+            }
+            WHEN("Set criterion without a name") {
+                REQUIRE_FAILURE(pfwSetCriterion(pfw, NULL, 2));
+            }
+            WHEN("Set not existing criterion") {
+                REQUIRE_FAILURE(pfwSetCriterion(pfw, "Do not exist", 3));
+            }
+            WHEN("Set criterion value") {
+                for(size_t i = 0; i < criterionNb; ++i) {
+                    const char *criterionName = criteria[i].name;
+                    CAPTURE(criterionName);
+                    REQUIRE_SUCCESS(pfwSetCriterion(pfw, criterionName, 3));
+                }
+                THEN("Get criterion value should return what was set") {
+                    for(size_t i = 0; i < criterionNb; ++i) {
+                        const char *criterionName = criteria[i].name;
+                        CAPTURE(criterionName);
+                        REQUIRE_SUCCESS(pfwGetCriterion(pfw, criterionName, &value));
+                        REQUIRE(value == 3);
+                    }
+                }
+            }
+            WHEN("Commit criteria without a pfw") {
+                REQUIRE(not pfwApplyConfigurations(NULL));
+            }
+            WHEN("Commit criteria of a started pfw") {
+                REQUIRE_SUCCESS(pfwApplyConfigurations(pfw));
+            }
+
+            WHEN("Bind parameter without a pfw") {
+                REQUIRE(pfwBindParameter(NULL, intParameterPath) == NULL);
+            }
+            WHEN("Bind parameter without a path") {
+                REQUIRE_FAILURE(pfwBindParameter(pfw, NULL) != NULL);
+            }
+            WHEN("Bind a non existing parameter") {
+                REQUIRE_FAILURE(pfwBindParameter(pfw, "do/not/exist") != NULL);
+            }
+
+            WHEN("Set an int parameter without a parameter handle") {
+                REQUIRE(not pfwSetIntParameter(NULL, value));
+            }
+            WHEN("Get an int parameter without a parameter handle") {
+                REQUIRE(not pfwGetIntParameter(NULL, &value));
+            }
+
+            GIVEN("An integer parameter handle") {
+                PfwParameterHandler *param = pfwBindParameter(pfw, intParameterPath);
+                REQUIRE_SUCCESS(param != NULL);
+
+                WHEN("Get an int parameter without an output value") {
+                    REQUIRE_FAILURE(pfwGetIntParameter(param, NULL));
+                }
+
+                WHEN("Set parameter out of range") {
+                    REQUIRE_FAILURE(pfwSetIntParameter(param, 101));
+                }
+
+                WHEN("Set parameter") {
+                    REQUIRE_SUCCESS(pfwSetIntParameter(param, 11));
+                    THEN("Get parameter should return what was set") {
+                        REQUIRE_SUCCESS(pfwGetIntParameter(param, &value));
+                        REQUIRE(value == 11);
+                    }
+                }
+
+                pfwUnbindParameter(param);
+            }
+
+            GIVEN("An string parameter handle") {
+                PfwParameterHandler *param = pfwBindParameter(pfw, stringParameterPath);
+                REQUIRE_SUCCESS(param != NULL);
+
+                WHEN("Get an int parameter without an output value") {
+                    REQUIRE_FAILURE(pfwGetStringParameter(param, NULL));
+                }
+
+                WHEN("Set parameter out of range") {
+                    REQUIRE_FAILURE(pfwSetStringParameter(param, "ko_1234567"));
+                }
+
+                WHEN("Set parameter") {
+                    const char *value;
+                    REQUIRE_SUCCESS(pfwSetStringParameter(param, "ok"));
+                    THEN("Get parameter should return what was set") {
+                        REQUIRE_SUCCESS(pfwGetStringParameter(param, &value));
+                        REQUIRE(value == std::string("ok"));
+                        pfwFree((void *)value);
+                    }
+                }
+
+                pfwUnbindParameter(param);
+            }
+        }
+
+        pfwDestroy(pfw);
+    }
+}
+
+SCENARIO("Get last error without a pfw") {
+    THEN("Should return NULL") {
+        CHECK(pfwGetLastError(NULL) == NULL);
+    }
+}