1 /* 2 * Copyright (c) 2011-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 <string> 35 #include <vector> 36 #include <stdint.h> 37 #include "XmlSink.h" 38 #include "XmlSource.h" 39 40 #include "PathNavigator.h" 41 42 class CXmlElementSerializingContext; 43 namespace utility 44 { 45 class ErrorContext; 46 } // namespace utility 47 48 class PARAMETER_EXPORT CElement : public IXmlSink, public IXmlSource 49 { 50 public: 51 CElement(const std::string &strName = ""); 52 ~CElement() override; 53 54 // Description 55 void setDescription(const std::string &strDescription); 56 const std::string &getDescription() const; 57 58 // Name / Path 59 const std::string &getName() const; 60 void setName(const std::string &strName); 61 bool rename(const std::string &strName, std::string &strError); 62 std::string getPath() const; 63 std::string getQualifiedPath() const; 64 65 // Creation / build 66 virtual bool init(std::string &strError); 67 virtual void clean(); 68 69 // Children management 70 void addChild(CElement *pChild); 71 bool removeChild(CElement *pChild); 72 void listChildren(std::string &strChildList) const; 73 std::string listQualifiedPaths(bool bDive, size_t level = 0) const; 74 void listChildrenPaths(std::string &strChildPathList) const; 75 76 // Hierarchy query 77 size_t getNbChildren() const; 78 CElement *findChildOfKind(const std::string &strKind); 79 const CElement *findChildOfKind(const std::string &strKind) const; 80 const CElement *getParent() const; 81 82 /** 83 * Get a child element (const) 84 * 85 * Note: this method will assert if given a wrong child index (>= number of children) 86 * 87 * @param[in] index the index of the child element from 0 to number of children - 1 88 * @return the child element 89 */ 90 const CElement *getChild(size_t index) const; 91 92 /** 93 * Get a child element 94 * 95 * Note: this method will assert if given a wrong child index (>= number of children) 96 * 97 * @param[in] index the index of the child element from 0 to number of children - 1 98 * @return the child element 99 */ 100 CElement *getChild(size_t index); 101 102 const CElement *findChild(const std::string &strName) const; 103 CElement *findChild(const std::string &strName); 104 const CElement *findDescendant(CPathNavigator &pathNavigator) const; 105 CElement *findDescendant(CPathNavigator &pathNavigator); 106 bool isDescendantOf(const CElement *pCandidateAscendant) const; 107 108 // From IXmlSink 109 bool fromXml(const CXmlElement &xmlElement, 110 CXmlSerializingContext &serializingContext) override; 111 112 // From IXmlSource 113 void toXml(CXmlElement &xmlElement, CXmlSerializingContext &serializingContext) const override; 114 115 /** 116 * Serialize the children to XML 117 * 118 * This method is virtual, to be derived in case a special treatment is 119 * needed before doing so. 120 * 121 * @param[in,out] xmlElement the XML Element below which the children must 122 * be serialized (which may or may not be the CElement 123 * object upon which this method is called) 124 * @param[in,out] serializingContext information about the serialization 125 */ 126 virtual void childrenToXml(CXmlElement &xmlElement, 127 CXmlSerializingContext &serializingContext) const; 128 129 // Content structure dump 130 std::string dumpContent(utility::ErrorContext &errorContext, const size_t depth = 0) const; 131 132 // Element properties 133 virtual void showProperties(std::string &strResult) const; 134 135 // Class kind 136 virtual std::string getKind() const = 0; 137 138 /** 139 * Fill the Description field of the Xml Element during XML composing. 140 * 141 * @param[in,out] xmlElement to fill with the description 142 */ 143 void setXmlDescriptionAttribute(CXmlElement &xmlElement) const; 144 145 /** 146 * Appends if found human readable description property. 147 * 148 * @param[out] strResult in which the description is wished to be appended. 149 */ 150 void showDescriptionProperty(std::string &strResult) const; 151 152 /** 153 * Returns Xml element name used for element XML importing/exporting functionalities 154 */ 155 virtual std::string getXmlElementName() const; 156 157 protected: 158 // Content dumping 159 virtual std::string logValue(utility::ErrorContext &errorContext) const; 160 161 // Hierarchy 162 CElement *getParent(); 163 164 /** 165 * Creates a child CElement from a child XML Element 166 * 167 * @param[in] childElement the XML element to create CElement from 168 * @param[in] elementSerializingContext the serializing context 169 * 170 * @return child a pointer on the CElement object that has been added to the tree 171 */ 172 CElement *createChild(const CXmlElement &childElement, 173 CXmlSerializingContext &elementSerializingContext); 174 175 static const std::string gDescriptionPropertyName; 176 177 private: 178 // Returns Name or Kind if no Name 179 std::string getPathName() const; 180 // Returns true if children dynamic creation is to be dealt with 181 virtual bool childrenAreDynamic() const; 182 // House keeping 183 void removeChildren(); 184 // Fill XmlElement during XML composing 185 void setXmlNameAttribute(CXmlElement &xmlElement) const; 186 187 // Name 188 std::string _strName; 189 190 // Description 191 std::string _strDescription; 192 193 // Child iterators 194 typedef std::vector<CElement *>::iterator ChildArrayIterator; 195 typedef std::vector<CElement *>::reverse_iterator ChildArrayReverseIterator; 196 // Children 197 std::vector<CElement *> _childArray; 198 // Parent 199 CElement *_pParent{nullptr}; 200 }; 201