YedXml - Add_Element


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

The method adds a new XML element into the XML internal tree of object instance pvO. The tree can be either loaded or empty.
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.
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:

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

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:

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

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
nd tag node</node>

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

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

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

Memory unavailable to perform operation.

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

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

Can't find closing bracket of XML element.

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

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

Tag termination is expected but not found.

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

The offset from which inserting the new node is invalid.

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