/*
|
* 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 ¶meterMgr);
|
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;
|
};
|
