reference.html 72.9 KB
Newer Older
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2
<html>
Michael R Sweet's avatar
Michael R Sweet committed
3
<head>
4 5
	<title>Documentation	</title>
	<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
Michael Sweet's avatar
Michael Sweet committed
6
	<meta name="creator" content="Mini-XML v2.11">
Michael R Sweet's avatar
Michael R Sweet committed
7
<style type="text/css"><!--
8
body, p, h1, h2, h3, h4 {
9
  font-family: "lucida grande", geneva, helvetica, arial, sans-serif;
10
}
11
div.body h1 {
12
  font-size: 250%;
13
  font-weight: bold;
14
  margin: 0;
15
}
16
div.body h2 {
17
  font-size: 250%;
18
  margin-top: 1.5em;
19
}
20
div.body h3 {
21
  font-size: 150%;
22
  margin-bottom: 0.5em;
23
  margin-top: 1.5em;
24
}
25
div.body h4 {
26
  font-size: 110%;
27
  margin-bottom: 0.5em;
28
  margin-top: 1.5em;
29
}
30
div.body h5 {
Michael R Sweet's avatar
Michael R Sweet committed
31 32
  font-size: 100%;
  margin-bottom: 0.5em;
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
  margin-top: 1.5em;
}
div.contents {
  background: #e8e8e8;
  border: solid thin black;
  padding: 10px;
}
div.contents h1 {
  font-size: 110%;
}
div.contents h2 {
  font-size: 100%;
}
div.contents ul.contents {
  font-size: 80%;
}
49
.class {
Michael R Sweet's avatar
Michael R Sweet committed
50
  border-bottom: solid 2px gray;
51
}
52 53 54 55 56
.constants {
}
.description {
  margin-top: 0.5em;
}
57 58
.discussion {
}
59
.enumeration {
Michael R Sweet's avatar
Michael R Sweet committed
60
  border-bottom: solid 2px gray;
61 62
}
.function {
Michael R Sweet's avatar
Michael R Sweet committed
63
  border-bottom: solid 2px gray;
64 65 66 67
  margin-bottom: 0;
}
.members {
}
68 69
.method {
}
70 71 72 73 74
.parameters {
}
.returnvalue {
}
.struct {
Michael R Sweet's avatar
Michael R Sweet committed
75
  border-bottom: solid 2px gray;
76 77
}
.typedef {
Michael R Sweet's avatar
Michael R Sweet committed
78
  border-bottom: solid 2px gray;
79 80
}
.union {
Michael R Sweet's avatar
Michael R Sweet committed
81
  border-bottom: solid 2px gray;
82 83 84 85
}
.variable {
}
code, p.code, pre, ul.code li {
86
  font-family: monaco, courier, monospace;
87
  font-size: 90%;
88 89 90 91 92 93 94 95 96 97 98 99 100
}
a:link, a:visited {
  text-decoration: none;
}
span.info {
  background: black;
  border: solid thin black;
  color: white;
  font-size: 80%;
  font-style: italic;
  font-weight: bold;
  white-space: nowrap;
}
Michael R Sweet's avatar
Michael R Sweet committed
101 102 103 104
h3 span.info, h4 span.info {
  float: right;
  font-size: 100%;
}
105
ul.code, ul.contents, ul.subcontents {
106 107
  list-style-type: none;
  margin: 0;
Michael R Sweet's avatar
Michael R Sweet committed
108
  padding-left: 0;
109 110 111 112
}
ul.code li {
  margin: 0;
}
Michael R Sweet's avatar
Michael R Sweet committed
113 114 115
ul.contents > li {
  margin-top: 1em;
}
116
ul.contents li ul.code, ul.contents li ul.subcontents {
Michael R Sweet's avatar
Michael R Sweet committed
117 118
  padding-left: 2em;
}
119
div.body dl {
120 121
  margin-top: 0;
}
122
div.body dt {
123 124 125
  font-style: italic;
  margin-top: 0;
}
126
div.body dd {
127 128
  margin-bottom: 0.5em;
}
129 130 131 132 133 134
h1.title {
}
h2.title {
  border-bottom: solid 2px black;
}
h3.title {
Michael R Sweet's avatar
Michael R Sweet committed
135
  border-bottom: solid 2px black;
136
}
Michael R Sweet's avatar
Michael R Sweet committed
137
--></style>
Michael R Sweet's avatar
Michael R Sweet committed
138 139
</head>
<body>
140
<div class='body'>
Michael Sweet's avatar
Michael Sweet committed
141
<h1 align='right'><a name='REFERENCE'>Appendix B - Library Reference</h1>
Michael R Sweet's avatar
Michael R Sweet committed
142
<h2 class="title">Contents</h2>
Michael R Sweet's avatar
Michael R Sweet committed
143
<ul class="contents">
Michael R Sweet's avatar
Michael R Sweet committed
144
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
	<li><a href="#mxmlAdd" title="Add a node to a tree.">mxmlAdd</a></li>
	<li><a href="#mxmlDelete" title="Delete a node and all of its children.">mxmlDelete</a></li>
	<li><a href="#mxmlElementDeleteAttr" title="Delete an attribute.">mxmlElementDeleteAttr</a></li>
	<li><a href="#mxmlElementGetAttr" title="Get an attribute.">mxmlElementGetAttr</a></li>
	<li><a href="#mxmlElementSetAttr" title="Set an attribute.">mxmlElementSetAttr</a></li>
	<li><a href="#mxmlElementSetAttrf" title="Set an attribute with a formatted value.">mxmlElementSetAttrf</a></li>
	<li><a href="#mxmlEntityAddCallback" title="Add a callback to convert entities to Unicode.">mxmlEntityAddCallback</a></li>
	<li><a href="#mxmlEntityGetName" title="Get the name that corresponds to the character value.">mxmlEntityGetName</a></li>
	<li><a href="#mxmlEntityGetValue" title="Get the character corresponding to a named entity.">mxmlEntityGetValue</a></li>
	<li><a href="#mxmlEntityRemoveCallback" title="Remove a callback.">mxmlEntityRemoveCallback</a></li>
	<li><a href="#mxmlFindElement" title="Find the named element.">mxmlFindElement</a></li>
	<li><a href="#mxmlFindPath" title="Find a node with the given path.">mxmlFindPath</a></li>
	<li><a href="#mxmlGetCDATA" title="Get the value for a CDATA node.">mxmlGetCDATA</a></li>
	<li><a href="#mxmlGetCustom" title="Get the value for a custom node.">mxmlGetCustom</a></li>
	<li><a href="#mxmlGetElement" title="Get the name for an element node.">mxmlGetElement</a></li>
	<li><a href="#mxmlGetFirstChild" title="Get the first child of an element node.">mxmlGetFirstChild</a></li>
	<li><a href="#mxmlGetInteger" title="Get the integer value from the specified node or its
162
first child.">mxmlGetInteger</a></li>
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
	<li><a href="#mxmlGetLastChild" title="Get the last child of an element node.">mxmlGetLastChild</a></li>
	<li><a href="#mxmlGetNextSibling" title="Return the node type...">mxmlGetNextSibling</a></li>
	<li><a href="#mxmlGetOpaque" title="Get an opaque string value for a node or its first child.">mxmlGetOpaque</a></li>
	<li><a href="#mxmlGetParent" title="Get the parent node.">mxmlGetParent</a></li>
	<li><a href="#mxmlGetPrevSibling" title="Get the previous node for the current parent.">mxmlGetPrevSibling</a></li>
	<li><a href="#mxmlGetReal" title="Get the real value for a node or its first child.">mxmlGetReal</a></li>
	<li><a href="#mxmlGetRefCount" title="Get the current reference (use) count for a node.">mxmlGetRefCount</a></li>
	<li><a href="#mxmlGetText" title="Get the text value for a node or its first child.">mxmlGetText</a></li>
	<li><a href="#mxmlGetType" title="Get the node type.">mxmlGetType</a></li>
	<li><a href="#mxmlGetUserData" title="Get the user data pointer for a node.">mxmlGetUserData</a></li>
	<li><a href="#mxmlIndexDelete" title="Delete an index.">mxmlIndexDelete</a></li>
	<li><a href="#mxmlIndexEnum" title="Return the next node in the index.">mxmlIndexEnum</a></li>
	<li><a href="#mxmlIndexFind" title="Find the next matching node.">mxmlIndexFind</a></li>
	<li><a href="#mxmlIndexGetCount" title="Get the number of nodes in an index.">mxmlIndexGetCount</a></li>
	<li><a href="#mxmlIndexNew" title="Create a new index.">mxmlIndexNew</a></li>
	<li><a href="#mxmlIndexReset" title="Reset the enumeration/find pointer in the index and
179
return the first node in the index.">mxmlIndexReset</a></li>
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
	<li><a href="#mxmlLoadFd" title="Load a file descriptor into an XML node tree.">mxmlLoadFd</a></li>
	<li><a href="#mxmlLoadFile" title="Load a file into an XML node tree.">mxmlLoadFile</a></li>
	<li><a href="#mxmlLoadString" title="Load a string into an XML node tree.">mxmlLoadString</a></li>
	<li><a href="#mxmlNewCDATA" title="Create a new CDATA node.">mxmlNewCDATA</a></li>
	<li><a href="#mxmlNewCustom" title="Create a new custom data node.">mxmlNewCustom</a></li>
	<li><a href="#mxmlNewElement" title="Create a new element node.">mxmlNewElement</a></li>
	<li><a href="#mxmlNewInteger" title="Create a new integer node.">mxmlNewInteger</a></li>
	<li><a href="#mxmlNewOpaque" title="Create a new opaque string.">mxmlNewOpaque</a></li>
	<li><a href="#mxmlNewReal" title="Create a new real number node.">mxmlNewReal</a></li>
	<li><a href="#mxmlNewText" title="Create a new text fragment node.">mxmlNewText</a></li>
	<li><a href="#mxmlNewTextf" title="Create a new formatted text fragment node.">mxmlNewTextf</a></li>
	<li><a href="#mxmlNewXML" title="Create a new XML document tree.">mxmlNewXML</a></li>
	<li><a href="#mxmlRelease" title="Release a node.">mxmlRelease</a></li>
	<li><a href="#mxmlRemove" title="Remove a node from its parent.">mxmlRemove</a></li>
	<li><a href="#mxmlRetain" title="Retain a node.">mxmlRetain</a></li>
	<li><a href="#mxmlSAXLoadFd" title="Load a file descriptor into an XML node tree
196
using a SAX callback.">mxmlSAXLoadFd</a></li>
197
	<li><a href="#mxmlSAXLoadFile" title="Load a file into an XML node tree
198
using a SAX callback.">mxmlSAXLoadFile</a></li>
199
	<li><a href="#mxmlSAXLoadString" title="Load a string into an XML node tree
200
using a SAX callback.">mxmlSAXLoadString</a></li>
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
	<li><a href="#mxmlSaveAllocString" title="Save an XML tree to an allocated string.">mxmlSaveAllocString</a></li>
	<li><a href="#mxmlSaveFd" title="Save an XML tree to a file descriptor.">mxmlSaveFd</a></li>
	<li><a href="#mxmlSaveFile" title="Save an XML tree to a file.">mxmlSaveFile</a></li>
	<li><a href="#mxmlSaveString" title="Save an XML node tree to a string.">mxmlSaveString</a></li>
	<li><a href="#mxmlSetCDATA" title="Set the element name of a CDATA node.">mxmlSetCDATA</a></li>
	<li><a href="#mxmlSetCustom" title="Set the data and destructor of a custom data node.">mxmlSetCustom</a></li>
	<li><a href="#mxmlSetCustomHandlers" title="Set the handling functions for custom data.">mxmlSetCustomHandlers</a></li>
	<li><a href="#mxmlSetElement" title="Set the name of an element node.">mxmlSetElement</a></li>
	<li><a href="#mxmlSetErrorCallback" title="Set the error message callback.">mxmlSetErrorCallback</a></li>
	<li><a href="#mxmlSetInteger" title="Set the value of an integer node.">mxmlSetInteger</a></li>
	<li><a href="#mxmlSetOpaque" title="Set the value of an opaque node.">mxmlSetOpaque</a></li>
	<li><a href="#mxmlSetReal" title="Set the value of a real number node.">mxmlSetReal</a></li>
	<li><a href="#mxmlSetText" title="Set the value of a text node.">mxmlSetText</a></li>
	<li><a href="#mxmlSetTextf" title="Set the value of a text node to a formatted string.">mxmlSetTextf</a></li>
	<li><a href="#mxmlSetUserData" title="Set the user data pointer for a node.">mxmlSetUserData</a></li>
	<li><a href="#mxmlSetWrapMargin" title="Set the wrap margin when saving XML data.">mxmlSetWrapMargin</a></li>
	<li><a href="#mxmlWalkNext" title="Walk to the next logical node in the tree.">mxmlWalkNext</a></li>
	<li><a href="#mxmlWalkPrev" title="Walk to the previous logical node in the tree.">mxmlWalkPrev</a></li>
219
</ul></li>
Michael R Sweet's avatar
Michael R Sweet committed
220
<li><a href="#TYPES">Data Types</a><ul class="code">
221 222 223
	<li><a href="#mxml_custom_destroy_cb_t" title="Custom data destructor">mxml_custom_destroy_cb_t</a></li>
	<li><a href="#mxml_custom_load_cb_t" title="Custom data load callback function">mxml_custom_load_cb_t</a></li>
	<li><a href="#mxml_custom_save_cb_t" title="Custom data save callback function">mxml_custom_save_cb_t</a></li>
224
	<li><a href="#mxml_entity_cb_t" title="Entity callback function">mxml_entity_cb_t</a></li>
225 226 227 228 229 230 231
	<li><a href="#mxml_error_cb_t" title="Error callback function">mxml_error_cb_t</a></li>
	<li><a href="#mxml_index_t" title="An XML node index.">mxml_index_t</a></li>
	<li><a href="#mxml_load_cb_t" title="Load callback function">mxml_load_cb_t</a></li>
	<li><a href="#mxml_node_t" title="An XML node.">mxml_node_t</a></li>
	<li><a href="#mxml_save_cb_t" title="Save callback function">mxml_save_cb_t</a></li>
	<li><a href="#mxml_sax_cb_t" title="SAX callback function">mxml_sax_cb_t</a></li>
	<li><a href="#mxml_sax_event_t" title="SAX event type.">mxml_sax_event_t</a></li>
Michael R Sweet's avatar
Michael R Sweet committed
232
	<li><a href="#mxml_type_t" title="The XML node type.">mxml_type_t</a></li>
Michael R Sweet's avatar
Michael R Sweet committed
233 234
</ul></li>
<li><a href="#ENUMERATIONS">Constants</a><ul class="code">
235 236
	<li><a href="#mxml_sax_event_e" title="SAX event type.">mxml_sax_event_e</a></li>
	<li><a href="#mxml_type_e" title="The XML node type.">mxml_type_e</a></li>
Michael R Sweet's avatar
Michael R Sweet committed
237
</ul></li>
238
</ul>
Michael R Sweet's avatar
Michael R Sweet committed
239 240
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
<h3 class="function"><a name="mxmlAdd">mxmlAdd</a></h3>
241
<p class="description">Add a node to a tree.</p>
Michael R Sweet's avatar
Michael R Sweet committed
242
<p class="code">
243
void mxmlAdd (<br>
Michael R Sweet's avatar
Michael R Sweet committed
244
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *parent,<br>
245
&nbsp;&nbsp;&nbsp;&nbsp;int where,<br>
Michael R Sweet's avatar
Michael R Sweet committed
246 247
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *child,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
248
);</p>
249
<h4 class="parameters">Parameters</h4>
250 251
<dl>
<dt>parent</dt>
252
<dd class="description">Parent node</dd>
253
<dt>where</dt>
254
<dd class="description">Where to add, MXML_ADD_BEFORE or MXML_ADD_AFTER</dd>
255
<dt>child</dt>
256
<dd class="description">Child node for where or MXML_ADD_TO_PARENT</dd>
257
<dt>node</dt>
258
<dd class="description">Node to add</dd>
259
</dl>
260
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
261
<p class="discussion">Adds the specified node to the parent. If the child argument is not
262 263 264 265 266
NULL, puts the new node before or after the specified child depending
on the value of the where argument. If the child argument is NULL,
puts the new node at the beginning of the child list (MXML_ADD_BEFORE)
or at the end of the child list (MXML_ADD_AFTER). The constant
MXML_ADD_TO_PARENT can be used to specify a NULL child pointer.</p>
Michael R Sweet's avatar
Michael R Sweet committed
267
<h3 class="function"><a name="mxmlDelete">mxmlDelete</a></h3>
268
<p class="description">Delete a node and all of its children.</p>
Michael R Sweet's avatar
Michael R Sweet committed
269
<p class="code">
270
void mxmlDelete (<br>
Michael R Sweet's avatar
Michael R Sweet committed
271
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
272
);</p>
273
<h4 class="parameters">Parameters</h4>
274 275
<dl>
<dt>node</dt>
276
<dd class="description">Node to delete</dd>
277
</dl>
278
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
279
<p class="discussion">If the specified node has a parent, this function first removes the
280
node from its parent using the mxmlRemove() function.</p>
Michael R Sweet's avatar
Michael R Sweet committed
281
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.4&nbsp;</span><a name="mxmlElementDeleteAttr">mxmlElementDeleteAttr</a></h3>
282
<p class="description">Delete an attribute.</p>
Michael R Sweet's avatar
Michael R Sweet committed
283
<p class="code">
284
void mxmlElementDeleteAttr (<br>
Michael R Sweet's avatar
Michael R Sweet committed
285
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node,<br>
286 287
&nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
);</p>
288
<h4 class="parameters">Parameters</h4>
289 290
<dl>
<dt>node</dt>
291
<dd class="description">Element</dd>
292
<dt>name</dt>
293
<dd class="description">Attribute name</dd>
294
</dl>
Michael R Sweet's avatar
Michael R Sweet committed
295
<h3 class="function"><a name="mxmlElementGetAttr">mxmlElementGetAttr</a></h3>
296
<p class="description">Get an attribute.</p>
Michael R Sweet's avatar
Michael R Sweet committed
297
<p class="code">
298
const char *mxmlElementGetAttr (<br>
Michael R Sweet's avatar
Michael R Sweet committed
299
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node,<br>
300 301
&nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
);</p>
302
<h4 class="parameters">Parameters</h4>
303 304
<dl>
<dt>node</dt>
305
<dd class="description">Element node</dd>
306
<dt>name</dt>
307
<dd class="description">Name of attribute</dd>
308
</dl>
309 310 311
<h4 class="returnvalue">Return Value</h4>
<p class="description">Attribute value or NULL</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
312
<p class="discussion">This function returns NULL if the node is not an element or the
313
named attribute does not exist.</p>
Michael R Sweet's avatar
Michael R Sweet committed
314
<h3 class="function"><a name="mxmlElementSetAttr">mxmlElementSetAttr</a></h3>
315
<p class="description">Set an attribute.</p>
Michael R Sweet's avatar
Michael R Sweet committed
316
<p class="code">
317
void mxmlElementSetAttr (<br>
Michael R Sweet's avatar
Michael R Sweet committed
318
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node,<br>
319 320 321
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
);</p>
322
<h4 class="parameters">Parameters</h4>
323 324
<dl>
<dt>node</dt>
325
<dd class="description">Element node</dd>
326
<dt>name</dt>
327
<dd class="description">Name of attribute</dd>
328
<dt>value</dt>
329
<dd class="description">Attribute value</dd>
330
</dl>
331
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
332
<p class="discussion">If the named attribute already exists, the value of the attribute
333 334 335
is replaced by the new string value. The string value is copied
into the element node. This function does nothing if the node is
not an element.</p>
Michael R Sweet's avatar
Michael R Sweet committed
336
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.3&nbsp;</span><a name="mxmlElementSetAttrf">mxmlElementSetAttrf</a></h3>
337
<p class="description">Set an attribute with a formatted value.</p>
Michael R Sweet's avatar
Michael R Sweet committed
338
<p class="code">
339
void mxmlElementSetAttrf (<br>
Michael R Sweet's avatar
Michael R Sweet committed
340
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node,<br>
341 342 343 344
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
&nbsp;&nbsp;&nbsp;&nbsp;...<br>
);</p>
345
<h4 class="parameters">Parameters</h4>
346 347
<dl>
<dt>node</dt>
348
<dd class="description">Element node</dd>
349
<dt>name</dt>
350
<dd class="description">Name of attribute</dd>
351
<dt>format</dt>
352
<dd class="description">Printf-style attribute value</dd>
353
<dt>...</dt>
354
<dd class="description">Additional arguments as needed</dd>
355
</dl>
356
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
357
<p class="discussion">If the named attribute already exists, the value of the attribute
358 359 360 361
is replaced by the new formatted string. The formatted string value is
copied into the element node. This function does nothing if the node
is not an element.

362
</p>
Michael R Sweet's avatar
Michael R Sweet committed
363
<h3 class="function"><a name="mxmlEntityAddCallback">mxmlEntityAddCallback</a></h3>
364
<p class="description">Add a callback to convert entities to Unicode.</p>
Michael R Sweet's avatar
Michael R Sweet committed
365
<p class="code">
366 367 368 369 370 371 372 373
int mxmlEntityAddCallback (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_entity_cb_t">mxml_entity_cb_t</a> cb<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>cb</dt>
<dd class="description">Callback function to add</dd>
</dl>
374 375
<h4 class="returnvalue">Return Value</h4>
<p class="description">0 on success, -1 on failure</p>
Michael R Sweet's avatar
Michael R Sweet committed
376
<h3 class="function"><a name="mxmlEntityGetName">mxmlEntityGetName</a></h3>
377
<p class="description">Get the name that corresponds to the character value.</p>
Michael R Sweet's avatar
Michael R Sweet committed
378
<p class="code">
379 380 381
const char *mxmlEntityGetName (<br>
&nbsp;&nbsp;&nbsp;&nbsp;int val<br>
);</p>
382
<h4 class="parameters">Parameters</h4>
383 384
<dl>
<dt>val</dt>
385
<dd class="description">Character value</dd>
386
</dl>
387 388 389
<h4 class="returnvalue">Return Value</h4>
<p class="description">Entity name or NULL</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
390 391
<p class="discussion">If val does not need to be represented by a named entity, NULL is returned.</p>
<h3 class="function"><a name="mxmlEntityGetValue">mxmlEntityGetValue</a></h3>
392
<p class="description">Get the character corresponding to a named entity.</p>
Michael R Sweet's avatar
Michael R Sweet committed
393
<p class="code">
394 395 396
int mxmlEntityGetValue (<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
);</p>
397
<h4 class="parameters">Parameters</h4>
398 399
<dl>
<dt>name</dt>
400
<dd class="description">Entity name</dd>
401
</dl>
402 403 404
<h4 class="returnvalue">Return Value</h4>
<p class="description">Character value or -1 on error</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
405
<p class="discussion">The entity name can also be a numeric constant. -1 is returned if the
406
name is not known.</p>
Michael R Sweet's avatar
Michael R Sweet committed
407
<h3 class="function"><a name="mxmlEntityRemoveCallback">mxmlEntityRemoveCallback</a></h3>
408
<p class="description">Remove a callback.</p>
Michael R Sweet's avatar
Michael R Sweet committed
409
<p class="code">
410 411 412 413 414 415 416 417
void mxmlEntityRemoveCallback (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_entity_cb_t">mxml_entity_cb_t</a> cb<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>cb</dt>
<dd class="description">Callback function to remove</dd>
</dl>
Michael R Sweet's avatar
Michael R Sweet committed
418
<h3 class="function"><a name="mxmlFindElement">mxmlFindElement</a></h3>
419
<p class="description">Find the named element.</p>
Michael R Sweet's avatar
Michael R Sweet committed
420 421 422 423
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlFindElement (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *top,<br>
424 425 426 427 428
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *attr,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *value,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int descend<br>
);</p>
429
<h4 class="parameters">Parameters</h4>
430 431
<dl>
<dt>node</dt>
432
<dd class="description">Current node</dd>
433
<dt>top</dt>
434
<dd class="description">Top node</dd>
435
<dt>name</dt>
436
<dd class="description">Element name or NULL for any</dd>
437
<dt>attr</dt>
438
<dd class="description">Attribute name, or NULL for none</dd>
439
<dt>value</dt>
440
<dd class="description">Attribute value, or NULL for any</dd>
441
<dt>descend</dt>
442
<dd class="description">Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST</dd>
443
</dl>
444 445 446
<h4 class="returnvalue">Return Value</h4>
<p class="description">Element node or NULL</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
447
<p class="discussion">The search is constrained by the name, attribute name, and value; any
448 449 450 451 452 453 454
NULL names or values are treated as wildcards, so different kinds of
searches can be implemented by looking for all elements of a given name
or all elements with a specific attribute. The descend argument determines
whether the search descends into child nodes; normally you will use
MXML_DESCEND_FIRST for the initial search and MXML_NO_DESCEND to find
additional direct descendents of the node. The top node argument
constrains the search to a particular node's children.</p>
455 456
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlFindPath">mxmlFindPath</a></h3>
<p class="description">Find a node with the given path.</p>
457
<p class="code">
458
<a href="#mxml_node_t">mxml_node_t</a> *mxmlFindPath (<br>
459 460 461 462 463 464 465 466 467 468 469
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *top,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *path<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>top</dt>
<dd class="description">Top node</dd>
<dt>path</dt>
<dd class="description">Path to element</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
470
<p class="description">Found node or NULL</p>
471 472 473
<h4 class="discussion">Discussion</h4>
<p class="discussion">The &quot;path&quot; is a slash-separated list of element names. The name &quot;*&quot; is
considered a wildcard for one or more levels of elements.  For example,
474 475 476 477
&quot;foo/one/two&quot;, &quot;bar/two/one&quot;, &quot;*/one&quot;, and so forth.<br>
<br>
The first child node of the found node is returned if the given node has
children and the first child is a value node.
478 479

</p>
480 481 482
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetCDATA">mxmlGetCDATA</a></h3>
<p class="description">Get the value for a CDATA node.</p>
<p class="code">
483
const char *mxmlGetCDATA (<br>
484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">CDATA value or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not a CDATA element.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetCustom">mxmlGetCustom</a></h3>
<p class="description">Get the value for a custom node.</p>
<p class="code">
500
const void *mxmlGetCustom (<br>
501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Custom value or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not a custom
value node.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetElement">mxmlGetElement</a></h3>
<p class="description">Get the name for an element node.</p>
<p class="code">
518
const char *mxmlGetElement (<br>
519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Element name or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not an element node.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetFirstChild">mxmlGetFirstChild</a></h3>
<p class="description">Get the first child of an element node.</p>
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetFirstChild (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">First child or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not an element node or if the node
has no children.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetInteger">mxmlGetInteger</a></h3>
<p class="description">Get the integer value from the specified node or its
first child.</p>
<p class="code">
int mxmlGetInteger (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Integer value or 0</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">0 is returned if the node (or its first child) is not an integer value node.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetLastChild">mxmlGetLastChild</a></h3>
<p class="description">Get the last child of an element node.</p>
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetLastChild (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Last child or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not an element node or if the node
has no children.

</p>
586
<h3 class="function"><a name="mxmlGetNextSibling">mxmlGetNextSibling</a></h3>
587 588
<p class="description">Return the node type...</p>
<p class="code">
589
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetNextSibling (<br>
590 591 592 593 594 595 596 597 598 599 600 601 602 603 604
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Get the next node for the current parent.</p>
<p class="discussion"><code>NULL</code> is returned if this is the last child for the current parent.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetOpaque">mxmlGetOpaque</a></h3>
<p class="description">Get an opaque string value for a node or its first child.</p>
<p class="code">
605
const char *mxmlGetOpaque (<br>
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Opaque string or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not an opaque
value node.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetParent">mxmlGetParent</a></h3>
<p class="description">Get the parent node.</p>
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetParent (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Parent node or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned for a root node.

</p>
637
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetPrevSibling">mxmlGetPrevSibling</a></h3>
638 639
<p class="description">Get the previous node for the current parent.</p>
<p class="code">
640
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetPrevSibling (<br>
641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Previous node or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if this is the first child for the current parent.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetReal">mxmlGetReal</a></h3>
<p class="description">Get the real value for a node or its first child.</p>
<p class="code">
double mxmlGetReal (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Real value or 0.0</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">0.0 is returned if the node (or its first child) is not a real value node.

</p>
671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetRefCount">mxmlGetRefCount</a></h3>
<p class="description">Get the current reference (use) count for a node.</p>
<p class="code">
int mxmlGetRefCount (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Reference count</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The initial reference count of new nodes is 1. Use the <a href="#mxmlRetain"><code>mxmlRetain</code></a>
and <a href="#mxmlRelease"><code>mxmlRelease</code></a> functions to increment and decrement a node's
reference count.

.</p>
690 691 692
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetText">mxmlGetText</a></h3>
<p class="description">Get the text value for a node or its first child.</p>
<p class="code">
693
const char *mxmlGetText (<br>
694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int *whitespace<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
<dt>whitespace</dt>
<dd class="description">1 if string is preceded by whitespace, 0 otherwise</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Text string or NULL</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not a text node.
The &quot;whitespace&quot; argument can be NULL.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetType">mxmlGetType</a></h3>
<p class="description">Get the node type.</p>
<p class="code">
<a href="#mxml_type_t">mxml_type_t</a> mxmlGetType (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Type of node</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>MXML_IGNORE</code> is returned if &quot;node&quot; is <code>NULL</code>.

</p>
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlGetUserData">mxmlGetUserData</a></h3>
<p class="description">Get the user data pointer for a node.</p>
<p class="code">
void *mxmlGetUserData (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>node</dt>
<dd class="description">Node to get</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">User data pointer</p>
Michael R Sweet's avatar
Michael R Sweet committed
741
<h3 class="function"><a name="mxmlIndexDelete">mxmlIndexDelete</a></h3>
742
<p class="description">Delete an index.</p>
Michael R Sweet's avatar
Michael R Sweet committed
743
<p class="code">
744
void mxmlIndexDelete (<br>
Michael R Sweet's avatar
Michael R Sweet committed
745
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_index_t">mxml_index_t</a> *ind<br>
746
);</p>
747
<h4 class="parameters">Parameters</h4>
748 749
<dl>
<dt>ind</dt>
750
<dd class="description">Index to delete</dd>
751
</dl>
Michael R Sweet's avatar
Michael R Sweet committed
752
<h3 class="function"><a name="mxmlIndexEnum">mxmlIndexEnum</a></h3>
753
<p class="description">Return the next node in the index.</p>
Michael R Sweet's avatar
Michael R Sweet committed
754 755 756
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlIndexEnum (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_index_t">mxml_index_t</a> *ind<br>
757
);</p>
758
<h4 class="parameters">Parameters</h4>
759 760
<dl>
<dt>ind</dt>
761
<dd class="description">Index to enumerate</dd>
762
</dl>
763 764 765
<h4 class="returnvalue">Return Value</h4>
<p class="description">Next node or NULL if there is none</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
766 767
<p class="discussion">Nodes are returned in the sorted order of the index.</p>
<h3 class="function"><a name="mxmlIndexFind">mxmlIndexFind</a></h3>
768
<p class="description">Find the next matching node.</p>
Michael R Sweet's avatar
Michael R Sweet committed
769 770 771
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlIndexFind (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_index_t">mxml_index_t</a> *ind,<br>
772 773 774
&nbsp;&nbsp;&nbsp;&nbsp;const char *element,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
);</p>
775
<h4 class="parameters">Parameters</h4>
776 777
<dl>
<dt>ind</dt>
778
<dd class="description">Index to search</dd>
779
<dt>element</dt>
780
<dd class="description">Element name to find, if any</dd>
781
<dt>value</dt>
782
<dd class="description">Attribute value, if any</dd>
783
</dl>
784 785 786
<h4 class="returnvalue">Return Value</h4>
<p class="description">Node or NULL if none found</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
787
<p class="discussion">You should call mxmlIndexReset() prior to using this function for
788 789 790
the first time with a particular set of &quot;element&quot; and &quot;value&quot;
strings. Passing NULL for both &quot;element&quot; and &quot;value&quot; is equivalent
to calling mxmlIndexEnum().</p>
791 792 793 794 795 796 797 798 799 800 801 802 803
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.7&nbsp;</span><a name="mxmlIndexGetCount">mxmlIndexGetCount</a></h3>
<p class="description">Get the number of nodes in an index.</p>
<p class="code">
int mxmlIndexGetCount (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_index_t">mxml_index_t</a> *ind<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>ind</dt>
<dd class="description">Index of nodes</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Number of nodes in index</p>
Michael R Sweet's avatar
Michael R Sweet committed
804
<h3 class="function"><a name="mxmlIndexNew">mxmlIndexNew</a></h3>
805
<p class="description">Create a new index.</p>
Michael R Sweet's avatar
Michael R Sweet committed
806 807 808
<p class="code">
<a href="#mxml_index_t">mxml_index_t</a> *mxmlIndexNew (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *node,<br>
809 810 811
&nbsp;&nbsp;&nbsp;&nbsp;const char *element,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *attr<br>
);</p>
812
<h4 class="parameters">Parameters</h4>
813 814
<dl>
<dt>node</dt>
815
<dd class="description">XML node tree</dd>
816
<dt>element</dt>
817
<dd class="description">Element to index or NULL for all</dd>
818
<dt>attr</dt>
819
<dd class="description">Attribute to index or NULL for none</dd>
820
</dl>
821 822 823
<h4 class="returnvalue">Return Value</h4>
<p class="description">New index</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
824
<p class="discussion">The index will contain all nodes that contain the named element and/or
825 826 827 828
attribute. If both &quot;element&quot; and &quot;attr&quot; are NULL, then the index will
contain a sorted list of the elements in the node tree.  Nodes are
sorted by element name and optionally by attribute value if the &quot;attr&quot;
argument is not NULL.</p>
Michael R Sweet's avatar
Michael R Sweet committed
829
<h3 class="function"><a name="mxmlIndexReset">mxmlIndexReset</a></h3>
830
<p class="description">Reset the enumeration/find pointer in the index and
831
return the first node in the index.</p>
Michael R Sweet's avatar
Michael R Sweet committed
832 833 834
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlIndexReset (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_index_t">mxml_index_t</a> *ind<br>
835
);</p>
836
<h4 class="parameters">Parameters</h4>
837 838
<dl>
<dt>ind</dt>
839
<dd class="description">Index to reset</dd>
840
</dl>
841 842 843
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or NULL if there is none</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
844
<p class="discussion">This function should be called prior to using mxmlIndexEnum() or
845
mxmlIndexFind() for the first time.</p>
Michael R Sweet's avatar
Michael R Sweet committed
846
<h3 class="function"><a name="mxmlLoadFd">mxmlLoadFd</a></h3>
847
<p class="description">Load a file descriptor into an XML node tree.</p>
Michael R Sweet's avatar
Michael R Sweet committed
848 849 850
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlLoadFd (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *top,<br>
851
&nbsp;&nbsp;&nbsp;&nbsp;int fd,<br>
Michael R Sweet's avatar
Michael R Sweet committed
852
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_load_cb_t">mxml_load_cb_t</a> cb<br>
853
);</p>
854
<h4 class="parameters">Parameters</h4>
855 856
<dl>
<dt>top</dt>
857
<dd class="description">Top node</dd>
858
<dt>fd</dt>
859
<dd class="description">File descriptor to read from</dd>
860
<dt>cb</dt>
861
<dd class="description">Callback function or MXML_NO_CALLBACK</dd>
862
</dl>
863 864 865
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or NULL if the file could not be read.</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
866
<p class="discussion">The nodes in the specified file are added to the specified top node.
867 868 869 870
If no top node is provided, the XML file MUST be well-formed with a
single parent node like &lt;?xml&gt; for the entire file. The callback
function returns the value type that should be used for child nodes.
If MXML_NO_CALLBACK is specified then all child nodes will be either
871 872 873
MXML_ELEMENT or MXML_TEXT nodes.<br>
<br>
The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK,
874
MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading
875
child nodes of the specified type.</p>
Michael R Sweet's avatar
Michael R Sweet committed
876
<h3 class="function"><a name="mxmlLoadFile">mxmlLoadFile</a></h3>
877
<p class="description">Load a file into an XML node tree.</p>
Michael R Sweet's avatar
Michael R Sweet committed
878 879 880
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlLoadFile (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *top,<br>
881
&nbsp;&nbsp;&nbsp;&nbsp;FILE *fp,<br>
Michael R Sweet's avatar
Michael R Sweet committed
882
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_load_cb_t">mxml_load_cb_t</a> cb<br>
883
);</p>
884
<h4 class="parameters">Parameters</h4>
885 886
<dl>
<dt>top</dt>
887
<dd class="description">Top node</dd>
888
<dt>fp</dt>
889
<dd class="description">File to read from</dd>
890
<dt>cb</dt>
891
<dd class="description">Callback function or MXML_NO_CALLBACK</dd>
892
</dl>
893 894 895
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or NULL if the file could not be read.</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
896
<p class="discussion">The nodes in the specified file are added to the specified top node.
897 898
If no top node is provided, the XML file MUST be well-formed with a
single parent node like &lt;?xml&gt; for the entire file. The callback
899 900
function returns the value type that should be used for child nodes.
If MXML_NO_CALLBACK is specified then all child nodes will be either
901 902 903
MXML_ELEMENT or MXML_TEXT nodes.<br>
<br>
The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK,
904
MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading
905
child nodes of the specified type.</p>
Michael R Sweet's avatar
Michael R Sweet committed
906
<h3 class="function"><a name="mxmlLoadString">mxmlLoadString</a></h3>
907
<p class="description">Load a string into an XML node tree.</p>
Michael R Sweet's avatar
Michael R Sweet committed
908 909 910
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlLoadString (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *top,<br>
911
&nbsp;&nbsp;&nbsp;&nbsp;const char *s,<br>
Michael R Sweet's avatar
Michael R Sweet committed
912
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_load_cb_t">mxml_load_cb_t</a> cb<br>
913
);</p>
914
<h4 class="parameters">Parameters</h4>
915 916
<dl>
<dt>top</dt>
917
<dd class="description">Top node</dd>
918
<dt>s</dt>
919
<dd class="description">String to load</dd>
920
<dt>cb</dt>
921
<dd class="description">Callback function or MXML_NO_CALLBACK</dd>
922
</dl>
923 924 925
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or NULL if the string has errors.</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
926
<p class="discussion">The nodes in the specified string are added to the specified top node.
927 928 929 930 931 932 933 934 935
If no top node is provided, the XML string MUST be well-formed with a
single parent node like &lt;?xml&gt; for the entire string. The callback
function returns the value type that should be used for child nodes.
If MXML_NO_CALLBACK is specified then all child nodes will be either
MXML_ELEMENT or MXML_TEXT nodes.<br>
<br>
The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK,
MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading
child nodes of the specified type.</p>
Michael R Sweet's avatar
Michael R Sweet committed
936
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.3&nbsp;</span><a name="mxmlNewCDATA">mxmlNewCDATA</a></h3>
937
<p class="description">Create a new CDATA node.</p>
Michael R Sweet's avatar
Michael R Sweet committed
938 939 940
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlNewCDATA (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *parent,<br>
941 942
&nbsp;&nbsp;&nbsp;&nbsp;const char *data<br>
);</p>
943
<h4 class="parameters">Parameters</h4>
944 945
<dl>
<dt>parent</dt>
946
<dd class="description">Parent node or MXML_NO_PARENT</dd>
947
<dt>data</dt>
948
<dd class="description">Data string</dd>
949
</dl>
950 951 952
<h4 class="returnvalue">Return Value</h4>
<p class="description">New node</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
953
<p class="discussion">The new CDATA node is added to the end of the specified parent's child
954
list. The constant MXML_NO_PARENT can be used to specify that the new
955 956
CDATA node has no parent. The data string must be nul-terminated and
is copied into the new node. CDATA nodes use the MXML_ELEMENT type.
957

958
</p>
Michael R Sweet's avatar
Michael R Sweet committed
959
<h3 class="function"><span class="info">&nbsp;Mini-XML 2.1&nbsp;</span><a name="mxmlNewCustom">mxmlNewCustom</a></h3>
960
<p class="description">Create a new custom data node.</p>
Michael R Sweet's avatar
Michael R Sweet committed
961 962 963
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlNewCustom (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *parent,<br>
964
&nbsp;&nbsp;&nbsp;&nbsp;void *data,<br>
Michael R Sweet's avatar
Michael R Sweet committed
965
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_custom_destroy_cb_t">mxml_custom_destroy_cb_t</a> destroy<br>
966
);</p>
967
<h4 class="parameters">Parameters</h4>
968 969
<dl>
<dt>parent</dt>
970
<dd class="description">Parent node or MXML_NO_PARENT</dd>
971
<dt>data</dt>
972
<dd class="description">Pointer to data</dd>
973
<dt>destroy</dt>
974
<dd class="description">Function to destroy data</dd>
975
</dl>
976 977 978
<h4 class="returnvalue">Return Value</h4>
<p class="description">New node</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
979
<p class="discussion">The new custom node is added to the end of the specified parent's child
980
list. The constant MXML_NO_PARENT can be used to specify that the new
981 982 983
element node has no parent. NULL can be passed when the data in the
node is not dynamically allocated or is separately managed.

984
</p>
Michael R Sweet's avatar
Michael R Sweet committed
985
<h3 class="function"><a name="mxmlNewElement">mxmlNewElement</a></h3>
986
<p class="description">Create a new element node.</p>
Michael R Sweet's avatar
Michael R Sweet committed
987 988 989
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlNewElement (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *parent,<br>
990 991
&nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
);</p>
992
<h4 class="parameters">Parameters</h4>
993 994
<dl>
<dt>parent</dt>
995
<dd class="description">Parent node or MXML_NO_PARENT</dd>
996
<dt>name</dt>
997
<dd class="description">Name of element</dd>
998
</dl>
999 1000 1001
<h4 class="returnvalue">Return Value</h4>
<p class="description">New node</p>
<h4 class="discussion">Discussion</h4>
Michael R Sweet's avatar
Michael R Sweet committed
1002
<p class="discussion">The new element node is added to the end of the specified parent's child
1003
list. The constant MXML_NO_PARENT can be used to specify that the new
1004
element node has no parent.</p>
Michael R Sweet's avatar
Michael R Sweet committed
1005
<h3 class="function"><a name="mxmlNewInteger">mxmlNewInteger</a></h3>
1006
<p class="description">Create a new integer node.</p>
Michael R Sweet's avatar
Michael R Sweet committed
1007 1008 1009
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlNewInteger (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#mxml_node_t">mxml_node_t</a> *parent,<br>
1010 1011
&nbsp;&nbsp;&nbsp;&nbsp;int integer<br>