Yate: XmlElement Class Reference

Yate

Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
XmlElement Class Reference

Xml Element. More...

`#include <yatexml.h>`

Inheritance diagram for XmlElement:

## Public Member Functions
| XmlElement (const NamedList &element, bool empty, XmlParent *parent=0)
| XmlElement (const char *name, bool complete=true)
| XmlElement (const char *name, const char *value, bool complete=true)
| XmlElement (const XmlElement &orig)
virtual | ~XmlElement ()
const char * | tag () const
bool | isDefaultNs () const
const String & | unprefixedTag () const
void | setUnprefixedTag (const String &s)
const String & | getTag () const
bool | getTag (const String *&tag, const String *&ns) const
virtual XmlElement * | xmlElement ()
virtual XmlElement * | element ()
virtual XmlSaxParser::Error | addChild (XmlChild *child)
virtual XmlChild * | removeChild (XmlChild *child, bool delObj=true)
virtual void | setCompleted ()
bool | completed () const
bool | empty () const
XmlElement * | parent () const
virtual XmlParent * | getParent ()
virtual void | setParent (XmlParent *parent)
virtual const String & | getName () const
virtual const NamedList & | getElement () const
const ObjList & | getChildren () const
void | clearChildren ()
const NamedList * | inheritedNs () const
void | setInheritedNs (const XmlElement *xml=0, bool inherit=true)
void | addInheritedNs (const NamedList &list)
XmlElement * | pop ()
virtual const String & | toString () const
void | toString (String &dump, bool escape=true, const String &indent=String::empty(), const String &origIndent=String::empty(), bool completeOnly=true, const String *auth=0) const
XmlElement * | findFirstChild (const String *name=0, const String *ns=0, bool noPrefix=true) const
XmlElement * | findFirstChild (const String &name, const String *ns=0, bool noPrefix=true) const
XmlElement * | findNextChild (const XmlElement *prev=0, const String *name=0, const String *ns=0, bool noPrefix=true) const
XmlElement * | findNextChild (const String &name, const XmlElement *prev=0, const String *ns=0, bool noPrefix=true) const
const String * | childText (const String &name, const String *ns=0, bool noPrefix=true) const
XmlChild * | getFirstChild ()
const String & | getText () const
XmlText * | setText (const char *text)
void | addText (const char *text)
void | addText (const void *buf, unsigned int len)
const NamedList & | attributes () const
unsigned int | copyAttributes (NamedList &list, const String &prefix) const
void | setAttributes (const NamedList &list, const String &prefix=String::empty(), bool skipPrefix=true)
void | setAttribute (const String &name, const char *value)
void | setAttributeValid (const String &name, const char *value)
const char * | attribute (const String &name) const
String * | getAttribute (const String &name) const
bool | hasAttribute (const String &name, const String &value) const
void | removeAttribute (const String &name)
String * | xmlns () const
String * | xmlnsAttribute (const String &name) const
bool | hasXmlns (const String &ns) const
bool | setXmlns (const String &name=String::empty(), bool addAttr=false, const String &value=String::empty())
virtual void | replaceParams (const NamedList &params)
XmlElement * | addChild (const char *name, const char *value=0)
XmlElement * | addChildHex (const char *name, const void *buf, unsigned int len)
Public Member Functions inherited from XmlChild
| XmlChild ()
virtual XmlComment * | xmlComment ()
virtual XmlCData * | xmlCData ()
virtual XmlText * | xmlText ()
virtual XmlDeclaration * | xmlDeclaration ()
virtual XmlDoctype * | xmlDoctype ()
Public Member Functions inherited from GenObject
| GenObject ()
virtual | ~GenObject ()
virtual bool | alive () const
virtual void | destruct ()
virtual const String & | traceId () const
virtual void * | getObject (const String &name) const
NamedCounter * | getObjCounter () const
NamedCounter * | setObjCounter (NamedCounter *counter)
Public Member Functions inherited from XmlParent
| XmlParent ()
virtual | ~XmlParent ()
virtual XmlDocument * | document ()
virtual XmlFragment * | fragment ()
XmlChild * | addChildSafe (XmlChild *child, XmlSaxParser::Error *code=0)
virtual void | reset ()
bool | hasChildren () const

## Static Public Member Functions
static bool | isXmlns (const String &str)
static XmlElement * | param2xml (NamedString *param, const String &tag, bool copyXml=false)
static NamedString * | xml2param (XmlElement *xml, const String *tag, bool copyXml=false)
static void | xml2param (NamedList &list, XmlElement *parent, const String *tag, bool copyXml=false)
Static Public Member Functions inherited from GenObject
static void * | getObject (const String &name, const GenObject *obj)
static bool | getObjCounting ()
static void | setObjCounting (bool enable)
static NamedCounter * | getObjCounter (const String &name, bool create=true)
static ObjList & | getObjCounters ()

## Static Public Attributes
static const String | s_ns
static const String | s_nsPrefix

## Detailed Description

Xml Element.

Xml Element from a Xml document

## Constructor & Destructor Documentation

## ◆ XmlElement() [1/4]

XmlElement | ( | const NamedList & | element,
|  | bool | empty,
|  | XmlParent * | parent = 0 )

Constructor

Parameters

  element | The NamedList name represent the element name and the param the attributes
  empty | False if has children
  parent | The parent of this element

Referenced by XmlElement::addChild().

## ◆ XmlElement() [2/4]

XmlElement | ( | const char * | name,
|  | bool | complete = true )

Constructor. Creates a new complete and empty element

Parameters

  name | The name of the element
  complete | False to build an incomplete element

## ◆ XmlElement() [3/4]

XmlElement | ( | const char * | name,
|  | const char * | value,
|  | bool | complete = true )

Constructor. Create a new element with a text child

Parameters

  name | The name of the element
  value | Element text child value
  complete | False to build an incomplete element

## ◆ XmlElement() [4/4]

XmlElement | ( | const XmlElement & | orig | ) |

Copy constructor

Parameters

  orig | Original XmlElement

## ◆ ~XmlElement()

virtual ~XmlElement | ( |  | ) |
| virtual

Destructor

## Member Function Documentation

## ◆ addChild() [1/2]

XmlElement * addChild | ( | const char * | name,
|  | const char * | value = 0 )
| inline

Safely build and add an XmlElement child

Parameters

  name | The name of the element
  value | Element text child value

Returns
  XmlElement pointer on success, NULL on failure

References XmlParent::addChildSafe(), and XmlElement::XmlElement().

## ◆ addChild() [2/2]

virtual XmlSaxParser::Error addChild | ( | XmlChild * | child | ) |
| virtual

Append a new child of this element

Parameters

  child | The child to append

Implements XmlParent.

Referenced by XmlElement::addChildHex().

## ◆ addChildHex()

XmlElement * addChildHex | ( | const char * | name,
|  | const void * | buf,
|  | unsigned int | len )
| inline

Safely build and add an XmlElement child with hexified value

Parameters

  name | The name of the element
  buf | Pointer to buffer to hexify
  len | Buffer length

Returns
  XmlElement pointer on success, NULL on failure

References XmlElement::addChild(), and XmlElement::addText().

## ◆ addInheritedNs()

void addInheritedNs | ( | const NamedList & | list | ) |

Add inherited namespaces from a list

Parameters

  list | The list of namespaces

## ◆ addText() [1/2]

void addText | ( | const char * | text | ) |

Add a text child

Parameters

  text | Non empty text to add

Referenced by XmlElement::addChildHex().

## ◆ addText() [2/2]

void addText | ( | const void * | buf,
|  | unsigned int | len )

Add a text child with hexified value

Parameters

  buf | Pointer to buffer to hexify
  len | Buffer length

## ◆ attribute()

const char * attribute | ( | const String & | name | ) | const
| inline

Obtain an attribute value for the given name

Parameters

  name | The name of the attribute

Returns
  Attribute value

References NamedList::getValue().

## ◆ attributes()

const NamedList & attributes | ( |  | ) | const
| inline

Retrieve the list of attributes

Returns
  Element attributes

## ◆ childText()

const String * childText | ( | const String & | name,
|  | const String * | ns = 0,
|  | bool | noPrefix = true ) const
| inline

Retrieve a child's text

Parameters

  name | Name (tag) of the child
  ns | Optional child namespace
  noPrefix | True to compare the tag without namespace prefix, false to include namespace prefix when comparing the given tag. This parameter is ignored ns is not 0

Returns
  Pointer to child's text, 0 if the child was not found

References XmlElement::findFirstChild(), and XmlElement::getText().

## ◆ clearChildren()

void clearChildren | ( |  | ) |
| inlinevirtual

Helper method to clear the children list

Reimplemented from XmlParent.

References XmlFragment::clearChildren().

## ◆ completed()

bool completed | ( |  | ) | const
| inline

Returns
  True if this element is completed

Referenced by XmlElement::pop().

## ◆ copyAttributes()

unsigned int copyAttributes | ( | NamedList & | list,
|  | const String & | prefix ) const

Copy element attributes to a list of parameters

Parameters

  list | Destination list
  prefix | Prefix to be added to each attribute name

Returns
  The number of attributes added to the destination list

## ◆ element()

virtual XmlElement * element | ( |  | ) |
| inlinevirtual

Get an XmlElement from this XmlParent

Returns
  This object

Reimplemented from XmlParent.

## ◆ empty()

bool empty | ( |  | ) | const
| inline

Returns
  True if this element is empty

## ◆ findFirstChild() [1/2]

XmlElement * findFirstChild | ( | const String & | name,
|  | const String * | ns = 0,
|  | bool | noPrefix = true ) const
| inline

Find the first XmlElement child of this XmlElement

Parameters

  name | Name of the child
  ns | Optional child namespace
  noPrefix | True to compare the tag without namespace prefix, false to include namespace prefix when comparing the given tag. This parameter is ignored if name is 0 or ns is not 0

Returns
  The first child element meeting the requested conditions

References XmlFragment::findElement(), and XmlElement::getChildren().

## ◆ findFirstChild() [2/2]

XmlElement * findFirstChild | ( | const String * | name = 0,
|  | const String * | ns = 0,
|  | bool | noPrefix = true ) const
| inline

Find the first XmlElement child of this XmlElement

Parameters

  name | Optional name of the child
  ns | Optional child namespace
  noPrefix | True to compare the tag without namespace prefix, false to include namespace prefix when comparing the given tag. This parameter is ignored if name is 0 or ns is not 0

Returns
  The first child element meeting the requested conditions

References XmlFragment::findElement(), and XmlElement::getChildren().

Referenced by XmlElement::childText(), XmlElement::findNextChild(), and XmlElement::pop().

## ◆ findNextChild() [1/2]

XmlElement * findNextChild | ( | const String & | name,
|  | const XmlElement * | prev = 0,
|  | const String * | ns = 0,
|  | bool | noPrefix = true ) const
| inline

Finds next XmlElement child of this XmlElement

Parameters

  name | Name of the child
  prev | Previous child
  ns | Optional child namespace
  noPrefix | True to compare the tag without namespace prefix, false to include namespace prefix when comparing the given tag. This parameter is ignored if name is 0 or ns is not 0

Returns
  The next found child if prev exists else the first

References XmlElement::findNextChild().

## ◆ findNextChild() [2/2]

XmlElement * findNextChild | ( | const XmlElement * | prev = 0,
|  | const String * | name = 0,
|  | const String * | ns = 0,
|  | bool | noPrefix = true ) const
| inline

Finds next XmlElement child of this XmlElement

Parameters

  prev | Previous child
  name | Optional name of the child
  ns | Optional child namespace
  noPrefix | True to compare the tag without namespace prefix, false to include namespace prefix when comparing the given tag. This parameter is ignored if name is 0 or ns is not 0

Returns
  The next found child if prev exists else the first

References ObjList::find(), XmlFragment::findElement(), XmlElement::findFirstChild(), XmlElement::getChildren(), and ObjList::skipNext().

Referenced by XmlElement::findNextChild().

## ◆ getAttribute()

String * getAttribute | ( | const String & | name | ) | const
| inline

Obtain an attribute value for the given name

Parameters

  name | The name of the attribute

Returns
  String pointer or 0 if not found

References NamedList::getParam().

Referenced by XmlElement::hasAttribute().

## ◆ getChildren()

const ObjList & getChildren | ( |  | ) | const
| inlinevirtual

Helper method to obtain the children list

Returns
  The children list

Reimplemented from XmlParent.

References XmlFragment::getChildren().

Referenced by XmlElement::findFirstChild(), XmlElement::findFirstChild(), and XmlElement::findNextChild().

## ◆ getElement()

virtual const NamedList & getElement | ( |  | ) | const
| inlinevirtual

Returns
  The held element

## ◆ getFirstChild()

XmlChild * getFirstChild | ( |  | ) |

Get first XmlChild of this XmlElement

Returns
  The first XmlChild found.

## ◆ getName()

virtual const String & getName | ( |  | ) | const
| inlinevirtual

Returns
  The name of this element

## ◆ getParent()

virtual XmlParent * getParent | ( |  | ) |
| inlinevirtual

Returns
  The parent of this element

## ◆ getTag() [1/2]

const String & getTag | ( |  | ) | const
| inline

Retrieve the element's tag (without prefix)

Returns
  Element tag

References NamedString::name().

## ◆ getTag() [2/2]

bool getTag | ( | const String *& | tag,
|  | const String *& | ns ) const

Retrieve the element's tag (without prefix) and namespace

Parameters

  tag | Pointer to element tag
  ns | Pointer to element's namespace (may be 0 for unprefixed tags)

Returns
  True if a namespace was found for the element tag or the tag is not prefixed

## ◆ getText()

const String & getText | ( |  | ) | const

Returns
  The first XmlText found in this XmlElement children

Referenced by XPath::anyValue(), and XmlElement::childText().

## ◆ hasAttribute()

bool hasAttribute | ( | const String & | name,
|  | const String & | value ) const
| inline

Check if the element has an attribute with a requested value

Parameters

  name | The name of the attribute
  value | The value to check

Returns
  True if the element has an attribute with the requested value

References XmlElement::getAttribute().

## ◆ hasXmlns()

bool hasXmlns | ( | const String & | ns | ) | const
| inline

Verify if this element belongs to the given namespace

Parameters

  ns | The namespace to compare with

Returns
  True if this element belongs to the given namespace

References XmlElement::xmlns().

## ◆ inheritedNs()

const NamedList * inheritedNs | ( |  | ) | const
| inline

Retrieve the list of inherited namespaces

Returns
  The list of inherited namespaces (or 0)

## ◆ isDefaultNs()

bool isDefaultNs | ( |  | ) | const
| inline

Check if this element must be processed in the default namespace (its tag is not prefixed)

Returns
  True if this element must be processed in the default namespace

## ◆ isXmlns()

static bool isXmlns | ( | const String & | str | ) |
| inlinestatic

Check if a string represents a namespace attribute name

Parameters

  str | The string to check

Returns
  True if the given string is the default namespace attribute name or a namespace attribute name prefix

References XmlElement::s_ns, XmlElement::s_nsPrefix, and String::startsWith().

## ◆ param2xml()

static XmlElement * param2xml | ( | NamedString * | param,
|  | const String & | tag,
|  | bool | copyXml = false )
| static

Build an XML element from a list parameter. Parameter name will be set in a 'name' attribute. Parameter value will be set in a 'value' attribute Handle NamedPointer parameters carrying DataBlock, NamedList and XmlElement objects (a 'type' attribute is added to the created element). DataBlock: Encode using BASE64 and add it as element text NamedList: The name is added as element text. The function is called again for each list parameter XmlElement: Added as child to newly created element

Parameters

  param | The parameter to convert
  tag | XmlElement tag
  copyXml | True to copy XmlElement objects instead of just remove them from the parameter

Returns
  XmlElement pointer or 0 on failure

## ◆ parent()

XmlElement * parent | ( |  | ) | const
| inline

Retrieve an XmlElement parent of this one

Returns
  XmlElement pointer or 0

References XmlParent::element().

## ◆ pop()

XmlElement * pop | ( |  | ) |
| inline

Extract the first child element

Returns
  XmlElement pointer or 0

References XmlElement::completed(), XmlElement::findFirstChild(), and XmlFragment::removeChild().

## ◆ removeAttribute()

void removeAttribute | ( | const String & | name | ) |
| inline

Remove an attribute

Parameters

  name | Attribute name

References NamedList::clearParam().

Referenced by XmlElement::setAttributeValid().

## ◆ removeChild()

virtual XmlChild * removeChild | ( | XmlChild * | child,
|  | bool | delObj = true )
| virtual

Remove a child

Parameters

  child | The child to remove
  delObj | True to delete the object

Returns
  XmlChild pointer if found and not deleted

Implements XmlParent.

## ◆ replaceParams()

virtual void replaceParams | ( | const NamedList & | params | ) |
| virtual

Replaces all ${paramname} in element's attributes and children with the corresponding parameters

Parameters

  params | List of parameters

Reimplemented from XmlChild.

## ◆ setAttribute()

void setAttribute | ( | const String & | name,
|  | const char * | value )
| inline

Add or replace an attribute

Parameters

  name | Attribute name
  value | Attribute value

References NamedList::setParam().

## ◆ setAttributes()

void setAttributes | ( | const NamedList & | list,
|  | const String & | prefix = String::empty(),
|  | bool | skipPrefix = true )
| inline

Set element attributes from a list of parameters

Parameters

  list | List of attributes
  prefix | Add only the attributes that start with this prefix. Set attributes from the whole parameter list if this parameter is empty
  skipPrefix | Skip over the prefix when building attribute name

References NamedList::copyParams(), and NamedList::copySubParams().

## ◆ setAttributeValid()

void setAttributeValid | ( | const String & | name,
|  | const char * | value )
| inline

Add or replace an attribute. Clears it if value is empty

Parameters

  name | Attribute name
  value | Attribute value

References XmlElement::removeAttribute(), and NamedList::setParam().

## ◆ setCompleted()

virtual void setCompleted | ( |  | ) |
| inlinevirtual

Notification for this element that is complete

## ◆ setInheritedNs()

void setInheritedNs | ( | const XmlElement * | xml = 0,
|  | bool | inherit = true )

Set inherited namespaces from a given element. Reset them anyway

Parameters

  xml | The source element used to set inherited namespaces
  inherit | Copy element's inherited namespaces if it doesn't have a parent

## ◆ setParent()

virtual void setParent | ( | XmlParent * | parent | ) |
| virtual

Set this element's parent. Update inherited namespaces

Returns
  The parent of this element

Reimplemented from XmlChild.

## ◆ setText()

XmlText * setText | ( | const char * | text | ) |

Set text for first XmlText element found in this XmlElement's children If child text element does not exist, create it and append it to the element's children.

Parameters

  text | Text to set to the XmlElement. If null, the first found XmlText element will be deleted.

Returns
  The set XmlText if text was set, null if an XmlText was deleted

## ◆ setUnprefixedTag()

void setUnprefixedTag | ( | const String & | s | ) |

Set element's unprefixed tag, don't change namespace prefix

Parameters

  s | New element's tag

## ◆ setXmlns()

bool setXmlns | ( | const String & | name = String::empty(),
|  | bool | addAttr = false,
|  | const String & | value = String::empty() )

Set the element's namespace

Parameters

  name | The namespace name (element prefix). Can be the default namespace attribute name (empty means the default one)
  addAttr | True to add a non empty, not repeating, namespace attribute to the list
  value | Namespace value (ignored if addAttr is false)

Returns
  True on success, false if another namespace exists with the same value

## ◆ tag()

const char * tag | ( |  | ) | const
| inline

Retrieve the element's tag

Returns
  The element's tag

## ◆ toString() [1/2]

virtual const String & toString | ( |  | ) | const
| inlinevirtual

Retrieve the element tag

Returns
  The element tag

Reimplemented from GenObject.

## ◆ toString() [2/2]

void toString | ( | String & | dump,
|  | bool | escape = true,
|  | const String & | indent = String::empty(),
|  | const String & | origIndent = String::empty(),
|  | bool | completeOnly = true,
|  | const String * | auth = 0 ) const

Build (append to) a String from this XmlElement

Parameters

  dump | The destination string
  escape | True if the attributes values need to be escaped
  indent | Spaces for output
  origIndent | Original indent
  completeOnly | True to build only if complete
  auth | Optional list of tag and attribute names to be replaced with '***'. This parameter can be used when the result will be printed to output to avoid printing authentication data to output. The array must end with an empty string

## ◆ unprefixedTag()

const String & unprefixedTag | ( |  | ) | const
| inline

Retrieve the element's tag unprefixed (namespace prefix removed)

Returns
  The element's tag unprefixed

References NamedString::name().

## ◆ xml2param() [1/2]

static void xml2param | ( | NamedList & | list,
|  | XmlElement * | parent,
|  | const String * | tag,
|  | bool | copyXml = false )
| static

Build and add list parameters from XML element children. Each parameter will be taken from 'name' and 'value' attributes. See param2xml for more info

Parameters

  list | Destination list
  parent | The XML element to process
  tag | Child XmlElement tag to handle
  copyXml | True to copy XmlElement objects instead of just remove them from parent

## ◆ xml2param() [2/2]

static NamedString * xml2param | ( | XmlElement * | xml,
|  | const String * | tag,
|  | bool | copyXml = false )
| static

Build a list parameter from xml element See param2xml for more info

Parameters

  xml | The XML element to process
  tag | Child XmlElement tag to handle
  copyXml | True to copy XmlElement objects instead of just remove them from parent

Returns
  NamedString pointer or 0 on failure

## ◆ xmlElement()

virtual XmlElement * xmlElement | ( |  | ) |
| inlinevirtual

Get an XmlElement from this XmlChild

Returns
  This object

Reimplemented from XmlChild.

## ◆ xmlns()

String * xmlns | ( |  | ) | const
| inline

Retrieve the element's namespace

Returns
  Element's namespace or 0 if not found

References XmlElement::s_ns, XmlElement::s_nsPrefix, and XmlElement::xmlnsAttribute().

Referenced by XmlElement::hasXmlns().

## ◆ xmlnsAttribute()

String * xmlnsAttribute | ( | const String & | name | ) | const

Retrieve a namespace attribute. Search in parent or inherited for it

Returns
  String pointer or 0 if not found

Referenced by XmlElement::xmlns().

## Member Data Documentation

## ◆ s_ns

const String s_ns
| static

Default namespace attribute name

Referenced by XmlElement::isXmlns(), and XmlElement::xmlns().

## ◆ s_nsPrefix

const String s_nsPrefix
| static

Namespace attribute name perfix

Referenced by XmlElement::isXmlns(), and XmlElement::xmlns().

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

- yatexml.h