1 /* 2 * Copyright (c) 2015, Intel Corporation 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without modification, 6 * are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright notice, 12 * this list of conditions and the following disclaimer in the documentation and/or 13 * other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its contributors 16 * may be used to endorse or promote products derived from this software without 17 * specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 #pragma once 31 32 #include "parameter_export.h" 33 34 #include <stdint.h> 35 #include <string> 36 #include <vector> 37 38 /** Forward declaration of private classes. 39 * Client should not use those class. 40 * They are not part of the public api and may be remove/renamed in any release. 41 * @{ 42 */ 43 class CParameterMgr; 44 class CConfigurableElement; 45 class CBaseParameter; 46 /** @} */ 47 48 /** TODO */ 49 class PARAMETER_EXPORT ElementHandle 50 { 51 public: 52 /** @return element's name. */ 53 std::string getName() const; 54 55 /** @return element's size in bytes. 56 * 57 * If the element size in bit is not a multiple of CHAR_BIT (8) 58 * it is rounded to the upper multiple. 59 * Effectively returning the element memory footprint. 60 */ 61 size_t getSize() const; 62 63 /** @return true if the element is a parameter, false otherwise. */ 64 bool isParameter() const; 65 66 /** @return a human readable description of the element. */ 67 std::string getDescription() const; 68 69 /** @return is the element and all its descendant not in a domain. 70 * 71 * Only rogue elements are allowed to be set. 72 * */ 73 bool isRogue() const; 74 75 /** @return true if the element is an array, false otherwise.*/ 76 bool isArray() const; 77 78 /** @return the parameter array length. 79 * 0 if the element is not an array (scalar). 80 */ 81 size_t getArrayLength() const; 82 83 /** @return element's path in the parameter hierarchy tree. */ 84 std::string getPath() const; 85 86 /** @return element's kind. 87 * 88 * Ie: a string identifying the type of Element. 89 */ 90 std::string getKind() const; 91 92 std::vector<ElementHandle> getChildren(); 93 94 /** Get mapping data of the element context 95 * 96 * Retrieve mapping data associated to a given key if any. 97 * If the key is not present in this element, query ancestors. 98 * 99 * @param[in] strKey the input mapping key 100 * @param[out] strValue the resulting mapping value in case of success 101 * @return true for if mapping key exists, false otherwise 102 */ 103 bool getMappingData(const std::string &strKey, std::string &strValue) const; 104 105 /** Gets element structure description as XML string 106 * 107 * @return the output XML string 108 */ 109 bool getStructureAsXML(std::string &xmlStructure, std::string &error) const; 110 111 /** Gets element settings as XML string 112 * 113 * @param[out] xmlValue the values to get 114 * @param[out] error On failure (false returned) will contain a human 115 * readable description of the error. 116 * On success (true returned) the content is not 117 * specified. 118 * 119 * @note returned value format depends on the current ParameterMgr format 120 * control properties, including value space and output raw format. 121 * @see ParameterMgrPlatformConnector::setOutputRawFormat 122 * @see ParameterMgrPlatformConnector::setValueSpace 123 * 124 * @return true on success, false on failure 125 */ 126 bool getAsXML(std::string &xmlValue, std::string &error) const; 127 128 /** Sets element settings as XML string 129 * 130 * @param[in] xmlValue the values to set 131 * @param[out] error On failure (false returned) will contain a human 132 * readable description of the error. 133 * On success (true returned) the content is not 134 * specified. 135 * 136 * @note 137 * - targeted element needs to be rogue for this operation to be allowed 138 * - structure of the passed XML element must match the targeted 139 * configurable element's one otherwise this operation will fail 140 * - expected value format depends on current value space. 141 * @see ParameterMgrPlatformConnector::valueSpaceIsRaw 142 * 143 * @return true on success, false otherwise 144 */ 145 bool setAsXML(const std::string &xmlValue, std::string &error); 146 147 /** Gets element settings in binary format 148 * 149 * @param[out] bytesValue the output vector 150 * @param[out] error unused 151 * 152 * @returns true 153 */ 154 bool getAsBytes(std::vector<uint8_t> &bytesValue, std::string &error) const; 155 156 /** Sets element settings in binary format 157 * 158 * @param[out] bytesValue the output vector 159 * @param[out] error On failure (false returned) will contain a human 160 * readable description of the error. 161 * On success (true returned) the content is not 162 * specified. 163 * 164 * @note 165 * - targeted element needs to be rogue for this operation to be allowed 166 * - size of the passed array must match that of the element 167 */ 168 bool setAsBytes(const std::vector<uint8_t> &bytesValue, std::string &error); 169 170 /** Access (get or set) parameters as different types. 171 * 172 * Will fail if the element is not a paramete. 173 * Array access will fail if the parameter is not an array. 174 * 175 * @param value if get, the value to get (in parameter) 176 * if set, the value to set (out parameter) 177 * 178 * Setting an array requires the std::vector size to match the arrayLength. 179 * Ie: value.size() == arrayLength() 180 * 181 * @param[out] error On failure (false returned) will contain a human 182 * readable description of the error. 183 * On success (true returned) the content is not 184 * specified. 185 * @return true if the access was successful, 186 * false otherwise (see error for the detail) 187 * @{ 188 */ 189 190 /** Boolean access @{ */ 191 bool getAsBoolean(bool &value, std::string &error) const; 192 bool setAsBoolean(bool value, std::string &error); 193 bool setAsBooleanArray(const std::vector<bool> &value, std::string &error); 194 bool getAsBooleanArray(std::vector<bool> &value, std::string &error) const; 195 /** @} */ 196 197 /** Integer Access @{ */ 198 bool setAsInteger(uint32_t value, std::string &error); 199 bool getAsInteger(uint32_t &value, std::string &error) const; 200 bool setAsIntegerArray(const std::vector<uint32_t> &value, std::string &error); 201 bool getAsIntegerArray(std::vector<uint32_t> &value, std::string &error) const; 202 /** @} */ 203 204 /** Signed Integer Access @{ */ 205 bool setAsSignedInteger(int32_t value, std::string &error); 206 bool getAsSignedInteger(int32_t &value, std::string &error) const; 207 bool setAsSignedIntegerArray(const std::vector<int32_t> &value, std::string &error); 208 bool getAsSignedIntegerArray(std::vector<int32_t> &value, std::string &error) const; 209 /** @} */ 210 211 /** Double Access @{ */ 212 bool setAsDouble(double value, std::string &error); 213 bool getAsDouble(double &value, std::string &error) const; 214 bool setAsDoubleArray(const std::vector<double> &value, std::string &error); 215 bool getAsDoubleArray(std::vector<double> &value, std::string &error) const; 216 /** @} */ 217 218 /** String Access @{ */ 219 bool setAsString(const std::string &value, std::string &error); 220 bool getAsString(std::string &value, std::string &error) const; 221 bool setAsStringArray(const std::vector<std::string> &value, std::string &error); 222 bool getAsStringArray(std::vector<std::string> &value, std::string &error) const; 223 /** @} */ 224 225 /** @} */ 226 227 protected: 228 ElementHandle(CConfigurableElement &element, CParameterMgr ¶meterMgr); 229 friend CParameterMgr; // So that it can build the handler 230 231 private: 232 template <class T> 233 bool setAs(const T value, std::string &error) const; 234 template <class T> 235 bool getAs(T &value, std::string &error) const; 236 237 CBaseParameter &getParameter(); 238 const CBaseParameter &getParameter() const; 239 240 /** Check that the parameter value can be modify. 241 * 242 * @param arrayLength[in] If accessing as an array: the new value array length 243 * Otherwise: 0 244 * @param error[out] If access is forbidden: a human readable message explaining why 245 * Otherwise: not modified. 246 * 247 * @return true if the parameter value can be retrieved, false otherwise. 248 */ 249 bool checkSetValidity(size_t arrayLength, std::string &error) const; 250 251 /** Check that the parameter value can be retrieved. 252 * 253 * @param asArray[in] true if accessing as an array, false otherwise. 254 * @param error[out] If access is forbidden, a human readable message explaining why 255 * Otherwise, not modified. 256 * 257 * @return true if the parameter value can be retrieved, false otherwise. 258 */ 259 bool checkGetValidity(bool asArray, std::string &error) const; 260 261 /** Reference to the handled Configurable element. */ 262 CConfigurableElement &mElement; 263 264 CParameterMgr &mParameterMgr; 265 }; 266