/* * 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 #include #include /** 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 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 &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 &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 &value, std::string &error); bool getAsBooleanArray(std::vector &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 &value, std::string &error); bool getAsIntegerArray(std::vector &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 &value, std::string &error); bool getAsSignedIntegerArray(std::vector &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 &value, std::string &error); bool getAsDoubleArray(std::vector &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 &value, std::string &error); bool getAsStringArray(std::vector &value, std::string &error) const; /** @} */ /** @} */ protected: ElementHandle(CConfigurableElement &element, CParameterMgr ¶meterMgr); friend CParameterMgr; // So that it can build the handler private: template bool setAs(const T value, std::string &error) const; template 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; };