YedXml - Add_Element

NAME:
Add_Element

SYNOPSIS:
SINT Add_Element (void *pvO,SCHAR *pscKeyElement,SINT siNumElement,
                  SCHAR *pscXMLAddBuf,SINT siFlagPreserve,SINT siOffset);

DESCRIPTION:
The method adds a new XML element into the XML internal tree of object instance pvO. The tree can be either loaded or empty.
pscKeyElement
is a pointer to the tag that will be the parent of the new node; if the tree is empty and its value is NULL, the node will be the new root node of the tree.
siNumElement
is the 1-based number of occurrence of pscKeyElement tag into XML internal tree, to find for adding the new node as its child; this parameter is not considered if pscKeyElement has the value NULL. Read Find_Element documentation for major details about searching for a tag into the tree through these couple of parameters.
pscXMLAddBuf is a pointer to a valid XML buffer.
siFlagPreserve allows to handle content of pscXMLAddBuf XML buffer in this way:

XML_PRESERVE
Mantain XML buffer exactly as it is, with all escape characters like '\n' and '\t'.

XML_NOTPRESERVE
Drop all unnecessary escape characters before adding XML buffer into the tree.

siOffset is the offset from the beginning of the content of the parent node from which adding the new element. It can assume following values:

HEAD
Add the new element immediately at the beginning of the content of the parent node.

TAIL
Add the new element at the end of the content of the parent node.

Any other positive value is considered as an offset from beginning of the content of the parent node from which adding the new element.

A few examples:

// Adding a new root node into the tree of YedXml object 'this'
// preserving the XML buffer

Add_Element(this,NULL,0,"<node value \"22\">node\ncontent</node>",XML_PRESERVE,0);

// Adding a new node as a child of first 'node' element found,
// at the beginning of 'node' content, without preserving XML buffer

Add_Element(this,"node",1,"<child>\tchild\t content\n</child>",XML_NOTPRESERVE,HEAD);

// Adding a new node as a child of first 'child' element found,
// at the end of 'child' content, without preserving XML buffer

Add_Element(this,"child",1,"<node>second tag node\n</node>",XML_NOTPRESERVE,TAIL);

// Adding a new node as a child of second 'node' element found,
// from the forth byte of 'node' content, preserving XML buffer

Add_Element(this,"node",2,"<foo>tag foo\n</foo>",XML_PRESERVE,4);

// The XML internal buffer is at the end:

<node value="22"><child>child content<node>seco<foo>tag foo
</foo>
nd tag node</node>
</child>
node
content</node>

RETURN VALUE:
The method returns a value >= YPRSUCCESS if the new node has been correctly added. In case of error, it returns:

YPRINVALIDPARAM
One of input parameters is invalid, tipically one of the pointers to buffers: check them.

YPRCANTADDROOTELEM
Try to add a root element but an XML root element already exists into the XML tree.

YPRNOMEM
Memory unavailable to perform operation.

YPRINVALIDREM
XML buffer has comment tag ( '<!--' ) not properly closed.

YPRNOMORELEMENT
XML source buffer has no more elements to load. Although this case can seem normal, it shows a semantic problem in XML source buffer.

YPRNOCLOSE
Can't find closing bracket of XML element.

YPRLENINVALID
Try to copying buffer in a static memory area that cannot contain it. Expand the LEN_XML_STATIC_BUFFER constant and rebuild Yed.

YPRINVALIDVALUEATTR
Attribute value of an XML element is not between single or double quote.

YPRMISSINGTERM
Tag termination is expected but not found.

YPRNOBUFFER
Can't add the new element into an empty tree.

YPRINVALIDOFFSET
The offset from which inserting the new node is invalid.

YPRNOTFOUND
Can't find the tag parent in which inserting the new node.


http://yed.sourceforge.net