cXMLElement Class Reference
[Utility classes]

Represents an XML element in an XML configuration file. More...

#include <cxmlelement.h>

List of all members.

Classes

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

Public Member Functions

Common properties

virtual const char * getTagName () const
virtual const char * getSourceLocation () const
virtual const char * getNodeValue () const
virtual const char * getAttribute (const char *attr) const
virtual bool hasAttributes () const
virtual const cXMLAttributeMap & getAttributes () 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

cXMLElementgetFirstChildWithAttribute (const char *tagname, const char *attr, const char *attrvalue=NULL) const
cXMLElementgetElementById (const char *idattrvalue) const
cXMLElementgetElementByPath (const char *pathexpression, cXMLElement *root=NULL, ParamResolver *resolver=NULL) const
void debugDump () const
virtual std::string detailedInfo () const

Detailed 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.


Member Function Documentation

virtual std::string cXMLElement::detailedInfo (  )  const [virtual]

Returns tree contents in an XML-like format.

This method is only useful for debugging, because it does not perform necessary escaping in text nodes and attribute values, so the output is not necessarily well-formed XML.

virtual const char* cXMLElement::getAttribute ( const char *  attr  )  const [virtual]

Returns the value of the attribute with the given name.

It returns NULL if the given attribute is not found.

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

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 NULL if not found.

cXMLElement* cXMLElement::getElementByPath ( const char *  pathexpression,
cXMLElement root = NULL,
ParamResolver resolver = NULL 
) const

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

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

cXMLElement* cXMLElement::getFirstChildWithAttribute ( const char *  tagname,
const char *  attr,
const char *  attrvalue = NULL 
) const

Returns find first child element with the given tagname and the given attribute present, and (optionally) having the given value.

tagname might be NULL -- then any element with the given attribute will be accepted. Returns NULL if not found.

virtual cXMLElement* cXMLElement::getNextSibling (  )  const [virtual]

Returns pointer to the next sibling of this element (i.e.

the next child in the parent element). Returns NULL if there're no subsequent elements.

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

 for (cXMLElement *child=node->getFirstChild(); child; child = child->getNextSibling())
 {
    ...
 }
 
virtual cXMLElement* cXMLElement::getNextSiblingWithTag ( const char *  tagname  )  const [virtual]

Returns pointer to the next sibling of this element with the given tag name.

Return NULL 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=node->getFirstChildWithTag("foo"); child; child = child->getNextSiblingWithTag("foo"))
 {
     ...
 }
 
virtual const char* cXMLElement::getNodeValue (  )  const [virtual]

Returns text node in the element, or NULL otherwise.

(Mixing text and child elements is not supported.)

virtual cXMLElement* cXMLElement::getPreviousSibling (  )  const [virtual]

Returns pointer to the previous sibling of this element (i.e.

the previous child in the parent element). Returns NULL if there're no elements before this one.


The documentation for this class was generated from the following file:
Generated on Mon Jul 14 12:57:26 2014 for OMNeT++ Simulation Library by  doxygen 1.6.3