You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
520 lines
22 KiB
520 lines
22 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Mini-XML Programmers Manual, Version 2.7</TITLE>
|
|
<META NAME="author" CONTENT="Michael R. Sweet">
|
|
<META NAME="copyright" CONTENT="Copyright 2003-2011">
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-iso-8859-1">
|
|
<LINK REL="Start" HREF="index.html">
|
|
<LINK REL="Contents" HREF="index.html">
|
|
<LINK REL="Prev" HREF="install.html">
|
|
<LINK REL="Next" HREF="advanced.html">
|
|
<STYLE TYPE="text/css"><!--
|
|
BODY { font-family: sans-serif }
|
|
H1 { font-family: sans-serif }
|
|
H2 { font-family: sans-serif }
|
|
H3 { font-family: sans-serif }
|
|
H4 { font-family: sans-serif }
|
|
H5 { font-family: sans-serif }
|
|
H6 { font-family: sans-serif }
|
|
SUB { font-size: smaller }
|
|
SUP { font-size: smaller }
|
|
PRE { font-family: monospace }
|
|
A { text-decoration: none }
|
|
--></STYLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<A HREF="index.html">Contents</A>
|
|
<A HREF="install.html">Previous</A>
|
|
<A HREF="advanced.html">Next</A>
|
|
<HR NOSHADE>
|
|
<H1 align="right"><A name="BASICS"><IMG align="right" alt="2" height="100"
|
|
hspace="10" src="2.gif" width="100"></A>Getting Started with Mini-XML</H1>
|
|
<P>This chapter describes how to write programs that use Mini-XML to
|
|
access data in an XML file. Mini-XML provides the following
|
|
functionality:</P>
|
|
<UL>
|
|
<LI>Functions for creating and managing XML documents in memory.</LI>
|
|
<LI>Reading of UTF-8 and UTF-16 encoded XML files and strings.</LI>
|
|
<LI>Writing of UTF-8 encoded XML files and strings.</LI>
|
|
<LI>Support for arbitrary element names, attributes, and attribute
|
|
values with no preset limits, just available memory.</LI>
|
|
<LI>Support for integer, real, opaque ("CDATA"), and text data types in
|
|
"leaf" nodes.</LI>
|
|
<LI>"Find", "index", and "walk" functions for easily accessing data in
|
|
an XML document.</LI>
|
|
</UL>
|
|
<P>Mini-XML doesn't do validation or other types of processing on the
|
|
data based upon schema files or other sources of definition
|
|
information, nor does it support character entities other than those
|
|
required by the XML specification.</P>
|
|
<H2><A NAME="3_1">The Basics</A></H2>
|
|
<P>Mini-XML provides a single header file which you include:</P>
|
|
<PRE>
|
|
#include <mxml.h>
|
|
</PRE>
|
|
<P>The Mini-XML library is included with your program using the <KBD>
|
|
-lmxml</KBD> option:</P>
|
|
<PRE>
|
|
<KBD>gcc -o myprogram myprogram.c -lmxml ENTER</KBD>
|
|
</PRE>
|
|
<P>If you have the <TT>pkg-config(1)</TT> software installed, you can
|
|
use it to determine the proper compiler and linker options for your
|
|
installation:</P>
|
|
<PRE>
|
|
<KBD>pkg-config --cflags mxml ENTER</KBD>
|
|
<KBD>pkg-config --libs mxml ENTER</KBD>
|
|
</PRE>
|
|
<H2><A NAME="3_2">Nodes</A></H2>
|
|
<P>Every piece of information in an XML file is stored in memory in
|
|
"nodes". Nodes are defined by the <A href="reference.html#mxml_node_t"><TT>
|
|
mxml_node_t</TT></A> structure. Each node has a typed value, optional
|
|
user data, a parent node, sibling nodes (previous and next), and
|
|
potentially child nodes.</P>
|
|
<P>For example, if you have an XML file like the following:</P>
|
|
<PRE>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<data>
|
|
<node>val1</node>
|
|
<node>val2</node>
|
|
<node>val3</node>
|
|
<group>
|
|
<node>val4</node>
|
|
<node>val5</node>
|
|
<node>val6</node>
|
|
</group>
|
|
<node>val7</node>
|
|
<node>val8</node>
|
|
</data>
|
|
</PRE>
|
|
<P>the node tree for the file would look like the following in memory:</P>
|
|
<PRE>
|
|
?xml version="1.0" encoding="utf-8"?
|
|
|
|
|
data
|
|
|
|
|
node - node - node - group - node - node
|
|
| | | | | |
|
|
val1 val2 val3 | val7 val8
|
|
|
|
|
node - node - node
|
|
| | |
|
|
val4 val5 val6
|
|
</PRE>
|
|
<P>where "-" is a pointer to the sibling node and "|" is a pointer to
|
|
the first child or parent node.</P>
|
|
<P>The <A href="reference.html#mxmlGetType"><TT>mxmlGetType</TT></A>
|
|
function gets the type of a node, one of <TT>MXML_CUSTOM</TT>, <TT>
|
|
MXML_ELEMENT</TT>, <TT>MXML_INTEGER</TT>, <TT>MXML_OPAQUE</TT>, <TT>
|
|
MXML_REAL</TT>, or <TT>MXML_TEXT</TT>. The parent and sibling nodes are
|
|
accessed using the <A href="reference.html#mxmlGetParent"><TT>
|
|
mxmlGetParent</TT></A>, <A href="#mxmlGetNext"><TT>mxmlGetNext</TT></A>,
|
|
and <A href="#mxmlGetPrevious"><TT>mxmlGetPrevious</TT></A> functions.
|
|
The <A href="reference.html#mxmlGetUserData"><TT>mxmlGetUserData</TT></A>
|
|
function gets any user data associated with the node.</P>
|
|
<H3><A NAME="3_2_1">CDATA Nodes</A></H3>
|
|
<P>CDATA (<TT>MXML_ELEMENT</TT>) nodes are created using the <A href="reference.html#mxmlNewCDATA">
|
|
<TT>mxmlNewCDATA</TT></A> function. The <A href="reference.html#mxmlGetCDATA">
|
|
<TT>mxmlGetCDATA</TT></A> function retrieves the CDATA string pointer
|
|
for a node.</P>
|
|
<BLOCKQUOTE><B>Note:</B>
|
|
<P>CDATA nodes are currently stored in memory as special elements. This
|
|
will be changed in a future major release of Mini-XML.</P>
|
|
</BLOCKQUOTE>
|
|
<H3><A NAME="3_2_2">Custom Nodes</A></H3>
|
|
<P>Custom (<TT>MXML_CUSTOM</TT>) nodes are created using the <A href="reference.html#mxmlNewCustom">
|
|
<TT>mxmlNewCustom</TT></A> function or using a custom load callback
|
|
specified using the <A href="reference.html#mxmlSetCustomHandlers"><TT>
|
|
mxmlSetCustomHandlers</TT></A> function. The <A href="reference.html#mxmlGetCustom">
|
|
<TT>mxmlGetCustom</TT></A> function retrieves the custom value pointer
|
|
for a node.</P>
|
|
<H3><A NAME="3_2_3">Comment Nodes</A></H3>
|
|
<P>Comment (<TT>MXML_ELEMENT</TT>) nodes are created using the <A href="reference.html#mxmlNewElement">
|
|
<TT>mxmlNewElement</TT></A> function. The <A href="reference.html#mxmlGetElement">
|
|
<TT>mxmlGetElement</TT></A> function retrieves the comment string
|
|
pointer for a node, including the surrounding "!--" and "--"
|
|
characters.</P>
|
|
<BLOCKQUOTE><B>Note:</B>
|
|
<P>Comment nodes are currently stored in memory as special elements.
|
|
This will be changed in a future major release of Mini-XML.</P>
|
|
</BLOCKQUOTE>
|
|
<H3><A NAME="3_2_4">Element Nodes</A></H3>
|
|
<P>Element (<TT>MXML_ELEMENT</TT>) nodes are created using the <A href="reference.html#mxmlNewElement">
|
|
<TT>mxmlNewElement</TT></A> function. The <A href="reference.html#mxmlGetElement">
|
|
<TT>mxmlGetElement</TT></A> function retrieves the element name, the <A href="reference.html#mxmlElementGetAttr">
|
|
<TT>mxmlElementGetAttr</TT></A> function retrieves the value string for
|
|
a named attribute associated with the element, and the <A href="reference.html#mxmlGetFirstChild">
|
|
<TT>mxmlGetFirstChild</TT></A> and <A href="reference.html#mxmlGetLastChild">
|
|
<TT>mxmlGetLastChild</TT></A> functions retrieve the first and last
|
|
child nodes for the element, respectively.</P>
|
|
<H3><A NAME="3_2_5">Integer Nodes</A></H3>
|
|
<P>Integer (<TT>MXML_INTEGER</TT>) nodes are created using the <A href="reference.html#mxmlNewInteger">
|
|
<TT>mxmlNewInteger</TT></A> function. The <A href="reference.html#mxmlGetInteger">
|
|
<TT>mxmlGetInteger</TT></A> function retrieves the integer value for a
|
|
node.</P>
|
|
<H3><A NAME="3_2_6">Opaque Nodes</A></H3>
|
|
<P>Opaque (<TT>MXML_OPAQUE</TT>) nodes are created using the <A href="reference.html#mxmlNewOpaque">
|
|
<TT>mxmlNewOpaque</TT></A> function. The <A href="reference.html#mxmlGetOpaque">
|
|
<TT>mxmlGetOpaque</TT></A> function retrieves the opaque string pointer
|
|
for a node. Opaque nodes are like string nodes but preserve all
|
|
whitespace between nodes.</P>
|
|
<H3><A NAME="3_2_7">Text Nodes</A></H3>
|
|
<P>Text (<TT>MXML_TEXT</TT>) nodes are created using the <A href="reference.html#mxmlNewText">
|
|
<TT>mxmlNewText</TT></A> and <A href="reference.html#mxmlNewTextf"><TT>
|
|
mxmlNewTextf</TT></A> functions. Each text node consists of a text
|
|
string and (leading) whitespace value - the <A href="reference.html#mxmlGetText">
|
|
<TT>mxmlGetText</TT></A> function retrieves the text string pointer and
|
|
whitespace value for a node.</P>
|
|
|
|
<!-- NEED 12 -->
|
|
<H3><A NAME="3_2_8">Processing Instruction Nodes</A></H3>
|
|
<P>Processing instruction (<TT>MXML_ELEMENT</TT>) nodes are created
|
|
using the <A href="reference.html#mxmlNewElement"><TT>mxmlNewElement</TT>
|
|
</A> function. The <A href="reference.html#mxmlGetElement"><TT>
|
|
mxmlGetElement</TT></A> function retrieves the processing instruction
|
|
string for a node, including the surrounding "?" characters.</P>
|
|
<BLOCKQUOTE><B>Note:</B>
|
|
<P>Processing instruction nodes are currently stored in memory as
|
|
special elements. This will be changed in a future major release of
|
|
Mini-XML.</P>
|
|
</BLOCKQUOTE>
|
|
<H3><A NAME="3_2_9">Real Number Nodes</A></H3>
|
|
<P>Real number (<TT>MXML_REAL</TT>) nodes are created using the <A href="reference.html#mxmlNewReal">
|
|
<TT>mxmlNewReal</TT></A> function. The <A href="reference.html#mxmlGetReal">
|
|
<TT>mxmlGetReal</TT></A> function retrieves the CDATA string pointer for
|
|
a node.</P>
|
|
|
|
<!-- NEED 15 -->
|
|
<H3><A NAME="3_2_10">XML Declaration Nodes</A></H3>
|
|
<P>XML declaration (<TT>MXML_ELEMENT</TT>) nodes are created using the <A
|
|
href="reference.html#mxmlNewXML"><TT>mxmlNewXML</TT></A> function. The <A
|
|
href="reference.html#mxmlGetElement"><TT>mxmlGetElement</TT></A>
|
|
function retrieves the XML declaration string for a node, including the
|
|
surrounding "?" characters.</P>
|
|
<BLOCKQUOTE><B>Note:</B>
|
|
<P>XML declaration nodes are currently stored in memory as special
|
|
elements. This will be changed in a future major release of Mini-XML.</P>
|
|
</BLOCKQUOTE>
|
|
<!-- NEW PAGE -->
|
|
<H2><A NAME="3_3">Creating XML Documents</A></H2>
|
|
<P>You can create and update XML documents in memory using the various <TT>
|
|
mxmlNew</TT> functions. The following code will create the XML document
|
|
described in the previous section:</P>
|
|
<PRE>
|
|
mxml_node_t *xml; /* <?xml ... ?> */
|
|
mxml_node_t *data; /* <data> */
|
|
mxml_node_t *node; /* <node> */
|
|
mxml_node_t *group; /* <group> */
|
|
|
|
xml = mxmlNewXML("1.0");
|
|
|
|
data = mxmlNewElement(xml, "data");
|
|
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val1");
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val2");
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val3");
|
|
|
|
group = mxmlNewElement(data, "group");
|
|
|
|
node = mxmlNewElement(group, "node");
|
|
mxmlNewText(node, 0, "val4");
|
|
node = mxmlNewElement(group, "node");
|
|
mxmlNewText(node, 0, "val5");
|
|
node = mxmlNewElement(group, "node");
|
|
mxmlNewText(node, 0, "val6");
|
|
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val7");
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val8");
|
|
</PRE>
|
|
|
|
<!-- NEED 6 -->
|
|
<P>We start by creating the declaration node common to all XML files
|
|
using the <A href="reference.html#mxmlNewXML"><TT>mxmlNewXML</TT></A>
|
|
function:</P>
|
|
<PRE>
|
|
xml = mxmlNewXML("1.0");
|
|
</PRE>
|
|
<P>We then create the <TT><data></TT> node used for this document using
|
|
the <A href="reference.html#mxmlNewElement"><TT>mxmlNewElement</TT></A>
|
|
function. The first argument specifies the parent node (<TT>xml</TT>)
|
|
while the second specifies the element name (<TT>data</TT>):</P>
|
|
<PRE>
|
|
data = mxmlNewElement(xml, "data");
|
|
</PRE>
|
|
<P>Each <TT><node>...</node></TT> in the file is created using the <TT>
|
|
mxmlNewElement</TT> and <A href="reference.html#mxmlNewText"><TT>
|
|
mxmlNewText</TT></A> functions. The first argument of <TT>mxmlNewText</TT>
|
|
specifies the parent node (<TT>node</TT>). The second argument
|
|
specifies whether whitespace appears before the text - 0 or false in
|
|
this case. The last argument specifies the actual text to add:</P>
|
|
<PRE>
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val1");
|
|
</PRE>
|
|
<P>The resulting in-memory XML document can then be saved or processed
|
|
just like one loaded from disk or a string.</P>
|
|
|
|
<!-- NEED 15 -->
|
|
<H2><A NAME="3_4">Loading XML</A></H2>
|
|
<P>You load an XML file using the <A href="reference.html#mxmlLoadFile"><TT>
|
|
mxmlLoadFile</TT></A> function:</P>
|
|
<PRE>
|
|
FILE *fp;
|
|
mxml_node_t *tree;
|
|
|
|
fp = fopen("filename.xml", "r");
|
|
tree = mxmlLoadFile(NULL, fp,
|
|
MXML_TEXT_CALLBACK);
|
|
fclose(fp);
|
|
</PRE>
|
|
<P>The first argument specifies an existing XML parent node, if any.
|
|
Normally you will pass <TT>NULL</TT> for this argument unless you are
|
|
combining multiple XML sources. The XML file must contain a complete
|
|
XML document including the <TT>?xml</TT> element if the parent node is <TT>
|
|
NULL</TT>.</P>
|
|
<P>The second argument specifies the stdio file to read from, as opened
|
|
by <TT>fopen()</TT> or <TT>popen()</TT>. You can also use <TT>stdin</TT>
|
|
if you are implementing an XML filter program.</P>
|
|
<P>The third argument specifies a callback function which returns the
|
|
value type of the immediate children for a new element node: <TT>
|
|
MXML_CUSTOM</TT>, <TT>MXML_IGNORE</TT>, <TT>MXML_INTEGER</TT>, <TT>
|
|
MXML_OPAQUE</TT>, <TT>MXML_REAL</TT>, or <TT>MXML_TEXT</TT>. Load
|
|
callbacks are described in detail in <A href="advanced.html#LOAD_CALLBACKS">
|
|
Chapter 3</A>. The example code uses the <TT>MXML_TEXT_CALLBACK</TT>
|
|
constant which specifies that all data nodes in the document contain
|
|
whitespace-separated text values. Other standard callbacks include <TT>
|
|
MXML_IGNORE_CALLBACK</TT>, <TT>MXML_INTEGER_CALLBACK</TT>, <TT>
|
|
MXML_OPAQUE_CALLBACK</TT>, and <TT>MXML_REAL_CALLBACK</TT>.</P>
|
|
<P>The <A href="reference.html#mxmlLoadString"><TT>mxmlLoadString</TT></A>
|
|
function loads XML node trees from a string:</P>
|
|
|
|
<!-- NEED 10 -->
|
|
<PRE>
|
|
char buffer[8192];
|
|
mxml_node_t *tree;
|
|
|
|
...
|
|
tree = mxmlLoadString(NULL, buffer,
|
|
MXML_TEXT_CALLBACK);
|
|
</PRE>
|
|
<P>The first and third arguments are the same as used for <TT>
|
|
mxmlLoadFile()</TT>. The second argument specifies the string or
|
|
character buffer to load and must be a complete XML document including
|
|
the <TT>?xml</TT> element if the parent node is <TT>NULL</TT>.</P>
|
|
|
|
<!-- NEED 15 -->
|
|
<H2><A NAME="3_5">Saving XML</A></H2>
|
|
<P>You save an XML file using the <A href="reference.html#mxmlSaveFile"><TT>
|
|
mxmlSaveFile</TT></A> function:</P>
|
|
<PRE>
|
|
FILE *fp;
|
|
mxml_node_t *tree;
|
|
|
|
fp = fopen("filename.xml", "w");
|
|
mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
|
|
fclose(fp);
|
|
</PRE>
|
|
<P>The first argument is the XML node tree to save. It should normally
|
|
be a pointer to the top-level <TT>?xml</TT> node in your XML document.</P>
|
|
<P>The second argument is the stdio file to write to, as opened by <TT>
|
|
fopen()</TT> or <TT>popen()</TT>. You can also use <TT>stdout</TT> if
|
|
you are implementing an XML filter program.</P>
|
|
<P>The third argument is the whitespace callback to use when saving the
|
|
file. Whitespace callbacks are covered in detail in <A href="SAVE_CALLBACKS">
|
|
Chapter 3</A>. The previous example code uses the <TT>MXML_NO_CALLBACK</TT>
|
|
constant to specify that no special whitespace handling is required.</P>
|
|
<P>The <A href="reference.html#mxmlSaveAllocString"><TT>
|
|
mxmlSaveAllocString</TT></A>, and <A href="reference.html#mxmlSaveString">
|
|
<TT>mxmlSaveString</TT></A> functions save XML node trees to strings:</P>
|
|
<PRE>
|
|
char buffer[8192];
|
|
char *ptr;
|
|
mxml_node_t *tree;
|
|
|
|
...
|
|
mxmlSaveString(tree, buffer, sizeof(buffer),
|
|
MXML_NO_CALLBACK);
|
|
|
|
...
|
|
ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
|
|
</PRE>
|
|
<P>The first and last arguments are the same as used for <TT>
|
|
mxmlSaveFile()</TT>. The <TT>mxmlSaveString</TT> function takes pointer
|
|
and size arguments for saving the XML document to a fixed-size buffer,
|
|
while <TT>mxmlSaveAllocString()</TT> returns a string buffer that was
|
|
allocated using <TT>malloc()</TT>.</P>
|
|
|
|
<!-- NEED 15 -->
|
|
<H3><A NAME="3_5_1">Controlling Line Wrapping</A></H3>
|
|
<P>When saving XML documents, Mini-XML normally wraps output lines at
|
|
column 75 so that the text is readable in terminal windows. The <A href="reference.html#mxmlSetWrapMargin">
|
|
<TT>mxmlSetWrapMargin</TT></A> function overrides the default wrap
|
|
margin:</P>
|
|
<PRE>
|
|
/* Set the margin to 132 columns */
|
|
mxmlSetWrapMargin(132);
|
|
|
|
/* Disable wrapping */
|
|
mxmlSetWrapMargin(0);
|
|
</PRE>
|
|
<H2><A NAME="3_6">Memory Management</A></H2>
|
|
<P>Once you are done with the XML data, use the <A href="reference.html#mxmlDelete">
|
|
<TT>mxmlDelete</TT></A> function to recursively free the memory that is
|
|
used for a particular node or the entire tree:</P>
|
|
<PRE>
|
|
mxmlDelete(tree);
|
|
</PRE>
|
|
<P>You can also use reference counting to manage memory usage. The <A href="reference.html#mxmlRetain">
|
|
<TT>mxmlRetain</TT></A> and <A href="reference.html#mxmlRelease"><TT>
|
|
mxmlRelease</TT></A> functions increment and decrement a node's use
|
|
count, respectively. When the use count goes to 0, <TT>mxmlRelease</TT>
|
|
will automatically call <TT>mxmlDelete</TT> to actually free the memory
|
|
used by the node tree. New nodes automatically start with a use count
|
|
of 1.</P>
|
|
|
|
<!-- NEW PAGE-->
|
|
<H2><A NAME="3_7">Finding and Iterating Nodes</A></H2>
|
|
<P>The <A href="reference.html#mxmlWalkPrev"><TT>mxmlWalkPrev</TT></A>
|
|
and <A href="reference.html#mxmlWalkNext"><TT>mxmlWalkNext</TT></A>
|
|
functions can be used to iterate through the XML node tree:</P>
|
|
<PRE>
|
|
mxml_node_t *node;
|
|
|
|
node = mxmlWalkPrev(current, tree,
|
|
MXML_DESCEND);
|
|
|
|
node = mxmlWalkNext(current, tree,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
<P>In addition, you can find a named element/node using the <A href="reference.html#mxmlFindElement">
|
|
<TT>mxmlFindElement</TT></A> function:</P>
|
|
<PRE>
|
|
mxml_node_t *node;
|
|
|
|
node = mxmlFindElement(tree, tree, "name",
|
|
"attr", "value",
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
<P>The <TT>name</TT>, <TT>attr</TT>, and <TT>value</TT> arguments can be
|
|
passed as <TT>NULL</TT> to act as wildcards, e.g.:</P>
|
|
|
|
<!-- NEED 4 -->
|
|
<PRE>
|
|
/* Find the first "a" element */
|
|
node = mxmlFindElement(tree, tree, "a",
|
|
NULL, NULL,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 5 -->
|
|
<PRE>
|
|
/* Find the first "a" element with "href"
|
|
attribute */
|
|
node = mxmlFindElement(tree, tree, "a",
|
|
"href", NULL,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 6 -->
|
|
<PRE>
|
|
/* Find the first "a" element with "href"
|
|
to a URL */
|
|
node = mxmlFindElement(tree, tree, "a",
|
|
"href",
|
|
"http://www.easysw.com/",
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 5 -->
|
|
<PRE>
|
|
/* Find the first element with a "src"
|
|
attribute */
|
|
node = mxmlFindElement(tree, tree, NULL,
|
|
"src", NULL,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 5 -->
|
|
<PRE>
|
|
/* Find the first element with a "src"
|
|
= "foo.jpg" */
|
|
node = mxmlFindElement(tree, tree, NULL,
|
|
"src", "foo.jpg",
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
<P>You can also iterate with the same function:</P>
|
|
<PRE>
|
|
mxml_node_t *node;
|
|
|
|
for (node = mxmlFindElement(tree, tree,
|
|
"name",
|
|
NULL, NULL,
|
|
MXML_DESCEND);
|
|
node != NULL;
|
|
node = mxmlFindElement(node, tree,
|
|
"name",
|
|
NULL, NULL,
|
|
MXML_DESCEND))
|
|
{
|
|
... do something ...
|
|
}
|
|
</PRE>
|
|
|
|
<!-- NEED 10 -->
|
|
<P>The <TT>MXML_DESCEND</TT> argument can actually be one of three
|
|
constants:</P>
|
|
<UL>
|
|
<LI><TT>MXML_NO_DESCEND</TT> means to not to look at any child nodes in
|
|
the element hierarchy, just look at siblings at the same level or
|
|
parent nodes until the top node or top-of-tree is reached.
|
|
<P>The previous node from "group" would be the "node" element to the
|
|
left, while the next node from "group" would be the "node" element to
|
|
the right.
|
|
<BR>
|
|
<BR></P>
|
|
</LI>
|
|
<LI><TT>MXML_DESCEND_FIRST</TT> means that it is OK to descend to the
|
|
first child of a node, but not to descend further when searching.
|
|
You'll normally use this when iterating through direct children of a
|
|
parent node, e.g. all of the "node" and "group" elements under the
|
|
"?xml" parent node in the example above.
|
|
<P>This mode is only applicable to the search function; the walk
|
|
functions treat this as <TT>MXML_DESCEND</TT> since every call is a
|
|
first time.
|
|
<BR>
|
|
<BR></P>
|
|
</LI>
|
|
<LI><TT>MXML_DESCEND</TT> means to keep descending until you hit the
|
|
bottom of the tree. The previous node from "group" would be the "val3"
|
|
node and the next node would be the first node element under "group".
|
|
<P>If you were to walk from the root node "?xml" to the end of the tree
|
|
with <TT>mxmlWalkNext()</TT>, the order would be:</P>
|
|
<P><TT>?xml data node val1 node val2 node val3 group node val4 node val5
|
|
node val6 node val7 node val8</TT></P>
|
|
<P>If you started at "val8" and walked using <TT>mxmlWalkPrev()</TT>,
|
|
the order would be reversed, ending at "?xml".</P>
|
|
</LI>
|
|
</UL>
|
|
<H2><A NAME="3_8">Finding Specific Nodes</A></H2>
|
|
<P>You can find specific nodes in the tree using the <A href="#mxmlFindValue">
|
|
<TT>mxmlFindPath</TT></A>, for example:</P>
|
|
<PRE>
|
|
mxml_node_t *value;
|
|
|
|
value = mxmlFindPath(tree, "path/to/*/foo/bar");
|
|
</PRE>
|
|
<P>The second argument is a "path" to the parent node. Each component of
|
|
the path is separated by a slash (/) and represents a named element in
|
|
the document tree or a wildcard (*) path representing 0 or more
|
|
intervening nodes.</P>
|
|
<HR NOSHADE>
|
|
<A HREF="index.html">Contents</A>
|
|
<A HREF="install.html">Previous</A>
|
|
<A HREF="advanced.html">Next</A>
|
|
</BODY>
|
|
</HTML>
|
|
|