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.


http://yed.sourceforge.net