YedXml - Find_Element
NAME:
Find_Element
SYNOPSIS:
SINT Find_Element
(void *pvO,SCHAR *pscKeyElement,SINT siNumElement,
XML_ELEMENT *pMParent,XML_ELEMENT *pMResult);
DESCRIPTION:
The method searches for an XML element with tag
pscKeyElement into XML
internal tree of object instance pvO
and returns a copy of this element through pointer pMResult.
pMParent is a pointer to the
XML element from which starting the search: if NULL,
searching starts from root XML element. Searching of XML
elements can start from an XML element other than root: in
this case, a pointer to this element can be passed through pMParent,
and the searching will be related to only the subtree with pMParent
element considered as root. siNumElement
is the relative number of XML element to find into XML
internal tree with pMParent as
root element: this 1-based index allows to extract multiple XML
elements with same tag into XML internal tree, as shown in
this example:
YedXml *p=New(YedXml);
XML_ELEMENT pFind;
...
/* search first occurrence of tag 'foo' from root element
and return a copy of it into pFind reference */
p->Find_Element(p,"foo",1,NULL,&pFind);
/* search second occurrence of tag 'foo', if exist */
p->Find_Element(p,"foo",2,NULL,&pFind);
WARNING : pMResult must point to a preallocated memory of correct size, as in the example above, because the method returns a copy of the XML element, not a pure pointer of it.
The method scans the internal XML tree from parent to all its child. Then, if the tree is like this:
<foo att="1" >
<ch>
<foo>second tag foo</foo>
</ch>
</foo>
<foo att="2" >
<ch/>
</foo>
a search for all occurrences of tag foo will return in sequence:
Format of XML_ELEMENT structure has shown in details in Get_XML_Declaration manual page.
RETURN
VALUE:
The method returns YPRSUCCESS if an
XML element has been found. In case of error, it returns:
YPRNOBUFFER
XML source buffer not previously loaded with Get_XML_Buffer
method.
YPRNOTFOUND
XML element does not exist into the XML tree.