parameter/include/ElementHandle.h

/*
 * 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.
 */
#pragma once

#include "parameter_export.h"

#include <stdint.h>
#include <string>
#include <vector>

/** Forward declaration of private classes.
 * Client should not use those class.
 * They are not part of the public api and may be remove/renamed in any release.
 * @{
 */
class CParameterMgr;
class CConfigurableElement;
class CBaseParameter;
/** @} */

/** TODO */
class PARAMETER_EXPORT ElementHandle
{
public:
    /** @return element's name. */
    std::string getName() const;

    /** @return element's size in bytes.
     *
     * If the element size in bit is not a multiple of CHAR_BIT (8)
     * it is rounded to the upper multiple.
     * Effectively returning the element memory footprint.
     */
    size_t getSize() const;

    /** @return true if the element is a parameter, false otherwise. */
    bool isParameter() const;

    /** @return a human readable description of the element. */
    std::string getDescription() const;

    /** @return is the element and all its descendant not in a domain.
     *
     * Only rogue elements are allowed to be set.
     * */
    bool isRogue() const;

    /** @return true if the element is an array, false otherwise.*/
    bool isArray() const;

    /** @return the parameter array length.
     *          0 if the element is not an array (scalar).
     */
    size_t getArrayLength() const;

    /** @return element's path in the parameter hierarchy tree. */
    std::string getPath() const;

    /** @return element's kind.
     *
     * Ie: a string identifying the type of Element.
     */
    std::string getKind() const;

    std::vector<ElementHandle> getChildren();

    /** Get mapping data of the element context
     *
     * Retrieve mapping data associated to a given key if any.
     * If the key is not present in this element, query ancestors.
     *
     * @param[in] strKey the input mapping key
     * @param[out] strValue the resulting mapping value in case of success
     * @return true for if mapping key exists, false otherwise
     */
    bool getMappingData(const std::string &strKey, std::string &strValue) const;

    /** Gets element structure description as XML string
     *
     * @return the output XML string
     */
    bool getStructureAsXML(std::string &xmlStructure, std::string &error) const;

    /** Gets element settings as XML string
     *
     * @param[out] xmlValue the values to get
     * @param[out] error On failure (false returned) will contain a human
     *                   readable description of the error.
     *                   On success (true returned) the content is not
     *                   specified.
     *
     * @note returned value format depends on the current ParameterMgr format
     *       control properties, including value space and output raw format.
     *       @see ParameterMgrPlatformConnector::setOutputRawFormat
     *       @see ParameterMgrPlatformConnector::setValueSpace
     *
     * @return true on success, false on failure
     */
    bool getAsXML(std::string &xmlValue, std::string &error) const;

    /** Sets element settings as XML string
     *
     * @param[in] xmlValue the values to set
     * @param[out] error On failure (false returned) will contain a human
     *                   readable description of the error.
     *                   On success (true returned) the content is not
     *                   specified.
     *
     * @note
     *    - targeted element needs to be rogue for this operation to be allowed
     *    - structure of the passed XML element must match the targeted
     *      configurable element's one otherwise this operation will fail
     *    - expected value format depends on current value space.
     *      @see ParameterMgrPlatformConnector::valueSpaceIsRaw
     *
     * @return true on success, false otherwise
     */
    bool setAsXML(const std::string &xmlValue, std::string &error);

    /** Gets element settings in binary format
     *
     * @param[out] bytesValue the output vector
     * @param[out] error unused
     *
     * @returns true
     */
    bool getAsBytes(std::vector<uint8_t> &bytesValue, std::string &error) const;

    /** Sets element settings in binary format
     *
     * @param[out] bytesValue the output vector
     * @param[out] error On failure (false returned) will contain a human
     *                   readable description of the error.
     *                   On success (true returned) the content is not
     *                   specified.
     *
     * @note
     *    - targeted element needs to be rogue for this operation to be allowed
     *    - size of the passed array must match that of the element
     */
    bool setAsBytes(const std::vector<uint8_t> &bytesValue, std::string &error);

    /** Access (get or set) parameters as different types.
     *
     * Will fail if the element is not a paramete.
     * Array access will fail if the parameter is not an array.
     *
     * @param value if get, the value to get (in parameter)
     *              if set, the value to set (out parameter)
     *
     * Setting an array requires the std::vector size to match the arrayLength.
     * Ie: value.size() == arrayLength()
     *
     * @param[out] error On failure (false returned) will contain a human
     *                   readable description of the error.
     *                   On success (true returned) the content is not
     *                   specified.
     * @return true if the access was successful,
     *         false otherwise (see error for the detail)
     * @{
     */

    /** Boolean access @{ */
    bool getAsBoolean(bool &value, std::string &error) const;
    bool setAsBoolean(bool value, std::string &error);
    bool setAsBooleanArray(const std::vector<bool> &value, std::string &error);
    bool getAsBooleanArray(std::vector<bool> &value, std::string &error) const;
    /** @} */

    /** Integer Access @{ */
    bool setAsInteger(uint32_t value, std::string &error);
    bool getAsInteger(uint32_t &value, std::string &error) const;
    bool setAsIntegerArray(const std::vector<uint32_t> &value, std::string &error);
    bool getAsIntegerArray(std::vector<uint32_t> &value, std::string &error) const;
    /** @} */

    /** Signed Integer Access @{ */
    bool setAsSignedInteger(int32_t value, std::string &error);
    bool getAsSignedInteger(int32_t &value, std::string &error) const;
    bool setAsSignedIntegerArray(const std::vector<int32_t> &value, std::string &error);
    bool getAsSignedIntegerArray(std::vector<int32_t> &value, std::string &error) const;
    /** @} */

    /** Double Access @{ */
    bool setAsDouble(double value, std::string &error);
    bool getAsDouble(double &value, std::string &error) const;
    bool setAsDoubleArray(const std::vector<double> &value, std::string &error);
    bool getAsDoubleArray(std::vector<double> &value, std::string &error) const;
    /** @} */

    /** String Access @{ */
    bool setAsString(const std::string &value, std::string &error);
    bool getAsString(std::string &value, std::string &error) const;
    bool setAsStringArray(const std::vector<std::string> &value, std::string &error);
    bool getAsStringArray(std::vector<std::string> &value, std::string &error) const;
    /** @} */

    /** @} */

protected:
    ElementHandle(CConfigurableElement &element, CParameterMgr &parameterMgr);
    friend CParameterMgr; // So that it can build the handler

private:
    template <class T>
    bool setAs(const T value, std::string &error) const;
    template <class T>
    bool getAs(T &value, std::string &error) const;

    CBaseParameter &getParameter();
    const CBaseParameter &getParameter() const;

    /** Check that the parameter value can be modify.
     *
     * @param arrayLength[in] If accessing as an array: the new value array length
     *                        Otherwise: 0
     * @param error[out] If access is forbidden: a human readable message explaining why
     *                   Otherwise: not modified.
     *
     * @return true if the parameter value can be retrieved, false otherwise.
     */
    bool checkSetValidity(size_t arrayLength, std::string &error) const;

    /** Check that the parameter value can be retrieved.
     *
     * @param asArray[in] true if accessing as an array, false otherwise.
     * @param error[out] If access is forbidden, a human readable message explaining why
     *                   Otherwise, not modified.
     *
     * @return true if the parameter value can be retrieved, false otherwise.
     */
    bool checkGetValidity(bool asArray, std::string &error) const;

    /** Reference to the handled Configurable element. */
    CConfigurableElement &mElement;

    CParameterMgr &mParameterMgr;
};