OMNeT++ Simulation Library  6.0.3
cXMLElement Class Reference

#include <cxmlelement.h>

Description

Represents an XML element in an XML configuration file.

XML-typed NED parameters are accessible as cXMLElement via the cPar::xmlValue() method.

cXMLElement provides readonly access to XML documents via a DOM-like API. (A full-featured DOM implementation would have been too bloated for the purpose of accessing readonly configuration files).

Features: readonly access (getter methods) only; represents only elements, attributes and text content (i.e. entities, processing instructions, comments are ignored); attributes are presented as part of an element node (not as separate attribute nodes as in DOM); mixed content model is not supported (element body cannot mix text with further elements); text is represented as a property of its enclosing element (and not as separate node as in DOM); CDATA sections are also represented as text (with the above restrictions); strings are presented in UTF-8 format (which is normal ASCII string if only characters 0x01-0x7F are used; encoding of the XML file itself may use arbitrary encoding provided it's supported by the underlying XML parser); no namespace support.

Supports XPath-like addressing via the getElementByPath() member function.

File inclusion is provided via limited support of the XInclude 1.0 spec, if the underlying XML parser supports it (e.g. Expat does not). An element <xi:include href="doc.xml"/> will be replaced with the content of the corresponding document. The "href" and "parse" attributes from the XInclude spec are supported.

Inheritance diagram for cXMLElement:
cObject noncopyable

Classes

class  ParamResolver
 Base class for classes that resolve parameters ($PARAM) that occur in in XPath expressions to their values. More...
 

Public Member Functions

Redefined cObject methods.
virtual const char * getName () const override
 
virtual std::string str () const override
 
virtual cObjectgetOwner () const override
 
virtual void forEachChild (cVisitor *v) override
 
Common properties
virtual const char * getTagName () const
 
virtual const char * getSourceFileName () const
 
virtual int getSourceLineNumber () const
 
virtual const char * getSourceLocation () const
 
virtual const char * getNodeValue () const
 
virtual const char * getAttribute (const char *attr) const
 
virtual bool hasAttributes () const
 
virtual cXMLAttributeMap getAttributes () const
 
virtual std::string getXML () const
 
Generic access to children and siblings
virtual cXMLElementgetParentNode () const
 
virtual bool hasChildren () const
 
virtual cXMLElementgetFirstChild () const
 
virtual cXMLElementgetLastChild () const
 
virtual cXMLElementgetNextSibling () const
 
virtual cXMLElementgetPreviousSibling () const
 
virtual cXMLElementgetFirstChildWithTag (const char *tagname) const
 
virtual cXMLElementgetNextSiblingWithTag (const char *tagname) const
 
virtual cXMLElementList getChildren () const
 
virtual cXMLElementList getChildrenByTagName (const char *tagname) const
 
virtual cXMLElementList getElementsByTagName (const char *tagname) const
 
Utility functions
virtual cXMLElementgetFirstChildWithAttribute (const char *tagname, const char *attr, const char *attrvalue=nullptr) const
 
virtual cXMLElementgetElementById (const char *idattrvalue) const
 
virtual cXMLElementgetElementByPath (const char *pathexpression, cXMLElement *root=nullptr, ParamResolver *resolver=nullptr) const
 
- Public Member Functions inherited from cObject
 cObject ()
 
 cObject (const cObject &other)=default
 
virtual ~cObject ()
 
virtual const char * getClassName () const
 
bool isName (const char *s) const
 
virtual const char * getFullName () const
 
virtual std::string getFullPath () const
 
virtual std::string getClassAndFullName () const
 
virtual std::string getClassAndFullPath () const
 
const cObjectgetThisPtr () const
 
virtual std::ostream & printOn (std::ostream &os) const
 
virtual cObjectdup () const
 
virtual void parsimPack (cCommBuffer *buffer) const
 
virtual void parsimUnpack (cCommBuffer *buffer)
 
virtual bool isOwnedObject () const
 
virtual bool isSoftOwner () const
 
cObjectfindObject (const char *name, bool deep=true)
 
virtual cClassDescriptorgetDescriptor () const
 
void copyNotSupported () const
 

Additional Inherited Members

- Protected Member Functions inherited from cObject
virtual void take (cOwnedObject *obj)
 
virtual void drop (cOwnedObject *obj)
 
void dropAndDelete (cOwnedObject *obj)
 

Member Function Documentation

◆ getName()

virtual const char* getName ( ) const
inlineoverridevirtual

Returns the tag name as object name.

Reimplemented from cObject.

◆ str()

virtual std::string str ( ) const
overridevirtual

Returns a one-line description of the element.

Reimplemented from cObject.

◆ getOwner()

virtual cObject* getOwner ( ) const
inlineoverridevirtual

Returns the parent element.

Reimplemented from cObject.

◆ forEachChild()

virtual void forEachChild ( cVisitor v)
overridevirtual

Enables traversing the object tree, performing some operation on each object. The operation is encapsulated in the particular subclass of cVisitor.

This method should be redefined in every subclass to call v->visit(obj) for every obj object contained.

Reimplemented from cObject.

◆ getTagName()

virtual const char* getTagName ( ) const
virtual

Returns the element name.

◆ getSourceFileName()

virtual const char* getSourceFileName ( ) const
inlinevirtual

Returns the file name this element originally came from.

◆ getSourceLineNumber()

virtual int getSourceLineNumber ( ) const
inlinevirtual

Returns the line number in the file this element originally came from.

◆ getSourceLocation()

virtual const char* getSourceLocation ( ) const
virtual

Returns a string containing a file/line position showing where this element originally came from.

◆ getNodeValue()

virtual const char* getNodeValue ( ) const
virtual

Returns text node in the element, or nullptr otherwise. (Mixing text and child elements is not supported.)

◆ getAttribute()

virtual const char* getAttribute ( const char *  attr) const
virtual

Returns the value of the attribute with the given name. It returns nullptr if the given attribute is not found.

◆ hasAttributes()

virtual bool hasAttributes ( ) const
virtual

Returns true if the element has attributes

◆ getAttributes()

virtual cXMLAttributeMap getAttributes ( ) const
virtual

Returns attributes in an a std::map.

◆ getXML()

virtual std::string getXML ( ) const
virtual

Returns the subtree as an XML fragment.

◆ getParentNode()

virtual cXMLElement* getParentNode ( ) const
virtual

Returns the parent element, or nullptr if this element has no parent.

◆ hasChildren()

virtual bool hasChildren ( ) const
virtual

Returns true if the element has child elements.

◆ getFirstChild()

virtual cXMLElement* getFirstChild ( ) const
virtual

Returns pointer to the first child element, or nullptr if this element has no children.

◆ getLastChild()

virtual cXMLElement* getLastChild ( ) const
virtual

Returns pointer to the last child element, or nullptr if this element has no children.

◆ getNextSibling()

virtual cXMLElement* getNextSibling ( ) const
virtual

Returns pointer to the next sibling of this element (i.e. the next child in the parent element). Returns nullptr if there're no subsequent elements.

getFirstChild() and getNextSibling() can be used to loop through the child list:

for (cXMLElement *child=element->getFirstChild(); child; child = child->getNextSibling())
{
   ...
}

◆ getPreviousSibling()

virtual cXMLElement* getPreviousSibling ( ) const
virtual

Returns pointer to the previous sibling of this element (i.e. the previous child in the parent element). Returns nullptr if there're no elements before this one.

◆ getFirstChildWithTag()

virtual cXMLElement* getFirstChildWithTag ( const char *  tagname) const
virtual

Returns pointer to the first child element with the given tag name, or nullptr if this element has no such children.

◆ getNextSiblingWithTag()

virtual cXMLElement* getNextSiblingWithTag ( const char *  tagname) const
virtual

Returns pointer to the next sibling of this element with the given tag name. Return nullptr if there're no such subsequent elements.

getFirstChildWithTag() and getNextSiblingWithTag() are a convient way to loop through elements with a certain tag name in the child list:

for (cXMLElement *child=element->getFirstChildWithTag("foo"); child; child = child->getNextSiblingWithTag("foo"))
{
    ...
}

◆ getChildren()

virtual cXMLElementList getChildren ( ) const
virtual

Returns list of child elements.

◆ getChildrenByTagName()

virtual cXMLElementList getChildrenByTagName ( const char *  tagname) const
virtual

Returns list of child elements with the given tag name.

◆ getElementsByTagName()

virtual cXMLElementList getElementsByTagName ( const char *  tagname) const
virtual

Returns list of contained elements with the given tag name, in preorder traversal order.

◆ getFirstChildWithAttribute()

virtual cXMLElement* getFirstChildWithAttribute ( const char *  tagname,
const char *  attr,
const char *  attrvalue = nullptr 
) const
virtual

Returns find first child element with the given tagname and the given attribute present, and (optionally) having the given value. tagname might be nullptr – then any element with the given attribute will be accepted. Returns nullptr if not found.

◆ getElementById()

virtual cXMLElement* getElementById ( const char *  idattrvalue) const
virtual

Returns the first element which has an "id" attribute with the given value. ("id" attributes are supposed to be unique in an XML document.) Returns nullptr if not found.

◆ getElementByPath()

virtual cXMLElement* getElementByPath ( const char *  pathexpression,
cXMLElement root = nullptr,
ParamResolver resolver = nullptr 
) const
virtual

Returns the first element designated by the given path expression. ("First" in the sense of preorder depth-first traversal.) Path expressions must be given in an XPath-like notation: they consist of path components (or "steps") separated by "/" or "//". A path component can be an element tag name, "*", "." or ".."; tag name and "*" can have an optional predicate in the form "[position]" or "[@attribute='value']". "/" means child element; "//" means a element any levels under the current one; ".", ".." and "*" mean what you expect them to: current element, parent element, element with any tag name.

Examples:

  • . – this element
  • ./foo – first "foo" child of this element
  • foo – same as ./foo (initial ./ can be omitted)
  • ./foo – first "foo" child of this element
  • ./foo/bar – first "bar" child of first "foo" child of this element
  • .//bar – first "bar" anywhere under this element (depth-first search!)
  • ./ * /bar – first "bar" child two levels below this element (remove the spaces!)
  • ./foo[0] – first "foo" child of this element
  • ./foo[1] – second "foo" child of this element
  • ./foo[@color='green'] – first "foo" child which has attribute "color" with value "green"
  • .//bar[1] – a "bar" anywhere under this element which is the second "bar" among its siblings
  • .// * [@color='yellow'] – an element anywhere under this element with attribute color="yellow" (remove the spaces!)
  • .// * [@color='yellow']/foo/bar – first "bar" child of first "foo" child of a "yellow-colored" element (remove the spaces!)

The method throws an exception if the path expression is invalid, and returns nullptr if the element is not found.


The documentation for this class was generated from the following file: