libsablot/doc/apidoc/sxp.xml

   1 <?xml version='1.0' encoding='ISO-8859-1' standalone='yes'?>
   2 <!DOCTYPE api>
   3 <API id="SXP">
   4
   5     <FOOT>
   6       &amp;copy; 2001-2003 Ginger Alliance<BR/>
   7       <I>revision 03-01-31</I><BR/>
   8     </FOOT>
   9
  10 <ENTRY id=".Introduction">
  11   <TYPE value="General"/>
  12   <DESCRIPTION>
  13     The <B>Sablotron XPath processor</B> (SXP) enables the user to evaluate
  14     an XPath query on a DOM document accessed via callback functions
  15     provided by the user. The interface to SXP is written in C. SXP
  16     is a part of Sablotron, an XSLT processor by Ginger Alliance.
  17   </DESCRIPTION>
  18   <SEEALSO value=".Building"/>
  19   <SEEALSO value=".Usage"/>
  20   <SEEALSO value=".Errors"/>
  21 </ENTRY>
  22
  23 <ENTRY id=".Building">
  24   <TYPE value="General"/>
  25   <DESCRIPTION>
  26     All declarations described in this document, if
  27     not specified otherwise, are to be found in the Sablotron header
  28     file <C>sxpath.h</C>. When building an executable using the SXP,
  29     include <C>sxpath.h</C> and link the Sablotron library (<C>-lsablot</C>).
  30   </DESCRIPTION>
  31 </ENTRY>
  32
  33 <ENTRY id=".Errors">
  34   <TYPE value="General"/>
  35   <DESCRIPTION>
  36     On error, most SXP interface functions output a Sablotron error
  37     message and return an error code which can be passed to functions
  38     like <C>SablotGetErrorMsg</C> (declared in <C>sablot.h</C>).
  39
  40     <P/>In the callbacks, in contrast, error handling has been kept to
  41     a minimum. Typically, in case of an error, a callback just returns
  42     a special value such as NULL.
  43   </DESCRIPTION>
  44 </ENTRY>
  45
  46 <ENTRY id=".Usage">
  47   <TYPE value="General"/>
  48   <DESCRIPTION>
  49     To work with SXP, the user needs to instantiate a
  50     <C>SablotSituation</C>, register a DOM handler (a set of DOM-like
  51     callback functions) using <C>SXP_registerDOMHandler</C>, and create a
  52     query context using <C>SXP_createQueryContext</C>.
  53   </DESCRIPTION>
  54   <EXAMPLE>
  55     SablotSituation S;
  56     SXP_QueryContext Q;
  57     DOMHandler my_domhandler=
  58     {
  59       &amp;getNodeType,
  60       /* ... more callbacks follow ... */
  61     };
  62     /* let us say the root is 123 */
  63     SXP_Node root = (SXP_Node) 123;
  64     SXP_char *result;
  65
  66     SablotCreateSituation(&amp;S);
  67     SXP_registerDOMHandler(S, &amp;my_domhandler);
  68     SXP_createQueryContext(S, &amp;Q);
  69     /* perform the query with the root as the context node */
  70     SXP_query(Q, "//*", root, 1, 1);
  71     SXP_getResultString(Q, &amp;result);
  72     puts(result);
  73     SXP_destroyQueryContext(Q);
  74     SablotDestroySituation(S);
  75   </EXAMPLE>
  76   <NOTE>
  77     For clarity, error checking has been omitted from the above
  78     excerpt.
  79   </NOTE>
  80 </ENTRY>
  81
  82 <!--
  83
  84   Types
  85
  86 -->
  87
  88 <ENTRY id="SablotSituation">
  89   <TYPE value="Types"/>
  90   <DESCRIPTION>
  91     The type representing a general "context" for Sablotron. Mainly
  92     used for error reporting. An object of this type can be created
  93     using <C>SablotCreateSituation</C>.
  94   </DESCRIPTION>
  95   <NOTE>
  96     <C>SablotSituation</C> is declared in <C>sablot.h</C>.
  97   </NOTE>
  98 </ENTRY>
  99
 100 <ENTRY id="SXP_char">
 101   <TYPE value="Types"/>
 102   <DESCRIPTION>
 103     SXP character type. Currently just UTF-8 encoded <C>char</C>.
 104   </DESCRIPTION>
 105 </ENTRY>
 106
 107 <ENTRY id="SXP_Node">
 108   <TYPE value="Types"/>
 109   <DESCRIPTION>
 110     A generic node type.
 111   </DESCRIPTION>
 112 </ENTRY>
 113
 114 <ENTRY id="SXP_Document">
 115   <TYPE value="Types"/>
 116   <DESCRIPTION>
 117     A document type. <C>SXP_Document</C> can be used in place of any
 118     <C>SXP_Node</C>, in which case it represents the document root
 119     node. A synonym for <C>SXP_Node</C> is <C>NodeHandle</C>.
 120   </DESCRIPTION>
 121 </ENTRY>
 122
 123 <ENTRY id="SXP_NodeList">
 124   <TYPE value="Types"/>
 125   <DESCRIPTION>
 126     A node list type. Node lists are returned by
 127     <C>SXP_getResultNodeset</C> and are manipulated using
 128     <C>SXP_getNodeListLength</C> and <C>SXP_getNodeListItem</C>.
 129   </DESCRIPTION>
 130 </ENTRY>
 131
 132 <ENTRY id="QueryContext">
 133   <TYPE value="Types"/>
 134   <DESCRIPTION>
 135     A type representing the context of a query, which can hold (1)
 136     namespace declarations for the next call to <C>SXP_query</C>, (2)
 137     variable bindings for the same, (3) the result of a
 138     <C>SXP_query</C>. An object of this type is created using
 139     <C>SXP_createQueryContext</C> and freed using
 140     <C>SXP_destroyQueryContext</C>. The evaluation result may be
 141     retrieved using functions like <C>SXP_getResultString</C>.
 142   </DESCRIPTION>
 143   <SEEALSO value="SXP_addVariableString"/>
 144   <SEEALSO value="SXP_addVariableBinding"/>
 145   <SEEALSO value="SXP_addNamespaceDeclaration"/>
 146 </ENTRY>
 147
 148 <!--
 149
 150   Enums
 151
 152 -->
 153
 154 <ENTRY id="SXP_ExpressionType">
 155   <TYPE value="Enums"/>
 156   <DESCRIPTION>
 157     The type for expressions in the SXP. Possible values include
 158     <C>SXP_NONE</C> (unknown type), <C>SXP_NUMBER</C>,
 159     <C>SXP_STRING</C>, <C>SXP_BOOLEAN</C> and <C>SXP_NODESET</C>.
 160   </DESCRIPTION>
 161   <SEEALSO value="SXP_getResultType"/>
 162 </ENTRY>
 163
 164 <ENTRY id="SXP_NodeType">
 165   <TYPE value="Enums"/>
 166   <DESCRIPTION>
 167     The type for nodes in the SXP. Possible values include:
 168     &lt;ul>
 169     &lt;li> ELEMENT_NODE,
 170     &lt;li> ATTRIBUTE_NODE,
 171     &lt;li> TEXT_NODE,
 172     &lt;li> PROCESSING_INSTRUCTION_NODE,
 173     &lt;li> COMMENT_NODE,
 174     &lt;li> DOCUMENT_NODE,
 175     &lt;li> NAMESPACE_NODE.
 176     &lt;/ul>
 177   </DESCRIPTION>
 178 </ENTRY>
 179
 180 <!--
 181
 182   Functions
 183
 184 -->
 185
 186 <ENTRY id="SablotCreateSituation">
 187   <TYPE value="Functions"/>
 188   <SYNTAX>
 189     SablotCreateSituation(sPtr)
 190     <PARAM name="sPtr" type="SablotSituation *">
 191       Pointer to where the result is to be stored.
 192     </PARAM>
 193     <PARAM name="(RET)" type="int">
 194       The error code.
 195     </PARAM>
 196   </SYNTAX>
 197   <DESCRIPTION>
 198     Creates a <C>SablotSituation</C> which is passed to many Sablotron
 199     functions and can be later destroyed by a call to <C>SablotDestroySituation</C>.
 200   </DESCRIPTION>
 201   <NOTE>
 202     <C>SablotCreateSituation</C> is declared in <C>sablot.h</C>.
 203   </NOTE>
 204 </ENTRY>
 205
 206 <ENTRY id="SablotDestroySituation">
 207   <TYPE value="Functions"/>
 208   <SYNTAX>
 209     SablotDestroySituation(S)
 210     <PARAM name="S" type="SablotSituation">
 211       The situation to be freed.
 212     </PARAM>
 213     <PARAM name="(RET)" type="int">
 214       The error code.
 215     </PARAM>
 216   </SYNTAX>
 217   <DESCRIPTION>
 218     Frees a <C>SablotSituation</C>.
 219   </DESCRIPTION>
 220   <NOTE>
 221     <C>SablotDestroySituation</C> is declared in <C>sablot.h</C>.
 222   </NOTE>
 223 </ENTRY>
 224
 225 <ENTRY id="SXP_registerDOMHandler">
 226   <TYPE value="Functions"/>
 227   <SYNTAX>
 228     SXP_registerDOMHandler(S, domh);
 229     <PARAM name="S" type="SablotSituation">
 230       The current situation.
 231     </PARAM>
 232     <PARAM name="domh" type="DOMHandler *">
 233       Pointer to the new DOM handler.
 234     </PARAM>
 235   </SYNTAX>
 236   <DESCRIPTION>
 237     Registers a new <C>DOMHandler</C> with the given
 238     <C>SablotSituation</C>. There may only be one DOM handler per
 239     situation. The DOM handler will receive all DOM requests made
 240     during evaluation with the situation S. To unregister the handler,
 241     use <C>SXP_unregisterDOMHandler</C>.
 242   </DESCRIPTION>
 243 </ENTRY>
 244
 245 <ENTRY id="SXP_unregisterDOMHandler">
 246   <TYPE value="Functions"/>
 247   <SYNTAX>
 248     SXP_unregisterDOMHandler(S)
 249     <PARAM name="S" type="SablotSituation">
 250       The current situation.
 251     </PARAM>
 252   </SYNTAX>
 253   <DESCRIPTION>
 254     Unregisters the <C>DOMHandler</C> registered with the given
 255     <C>SablotSituation</C>. All DOM requests will be processed in the
 256     default way.
 257   </DESCRIPTION>
 258 </ENTRY>
 259
 260 <ENTRY id="SXP_createQueryContext">
 261   <TYPE value="Functions"/>
 262   <SYNTAX>
 263     SXP_createQueryContext(S, Qptr)
 264     <PARAM name="S" type="SablotSituation">
 265       The current situation.
 266     </PARAM>
 267     <PARAM name="Qptr" type="QueryContext *">
 268       Pointer to where to store the query context.
 269     </PARAM>
 270     <PARAM name="(RET)" type="int">
 271       The error code.
 272     </PARAM>
 273   </SYNTAX>
 274   <DESCRIPTION>
 275     Creates a <C>QueryContext</C>.
 276   </DESCRIPTION>
 277 </ENTRY>
 278
 279 <ENTRY id="SXP_destroyQueryContext">
 280   <TYPE value="Functions"/>
 281   <SYNTAX>
 282     SXP_destroyQueryContext(Q)
 283     <PARAM name="Q" type="QueryContext">
 284       The query context to be deleted.
 285     </PARAM>
 286     <PARAM name="(RET)" type="int">
 287       The error code.
 288     </PARAM>
 289   </SYNTAX>
 290   <DESCRIPTION>
 291     Destroys a <C>QueryContext</C>, freeing all the memory it used,
 292     including any <C>SXP_query</C> result and the pending variable
 293     bindings and namespace declaration lists.
 294   </DESCRIPTION>
 295 </ENTRY>
 296
 297 <ENTRY id="SXP_addVariableBinding">
 298   <TYPE value="Functions"/>
 299   <SYNTAX>
 300     SXP_addVariableBinding(Q, name, source)
 301     <PARAM name="Q" type="QueryContext">
 302       The current query context.
 303     </PARAM>
 304     <PARAM name="name" type="const SXP_char*">
 305       The name of the variable.
 306     </PARAM>
 307     <PARAM name="source" type="QueryContext">
 308       Another <C>QueryContext</C> which has been evaluated
 309       already. The variable will be bound to its result expression.
 310     </PARAM>
 311     <PARAM name="(RET)" type="int">
 312       The error code.
 313     </PARAM>
 314   </SYNTAX>
 315   <DESCRIPTION>
 316     Binds a variable to the result expression of another
 317     <C>QueryContext</C>. The binding will only be in effect for the
 318     next <C>SXP_query</C>. <C>SXP_addVariableBinding</C> provides the
 319     only way to bind the variable to a node set.
 320   </DESCRIPTION>
 321   <SEEALSO value="SXP_addVariableNumber"/>
 322   <SEEALSO value="SXP_addVariableString"/>
 323   <SEEALSO value="SXP_addVariableBoolean"/>
 324 </ENTRY>
 325
 326 <ENTRY id="SXP_addVariableNumber">
 327   <TYPE value="Functions"/>
 328   <SYNTAX>
 329     SXP_addVariableNumber(Q, name, value)
 330     <PARAM name="Q" type="QueryContext">
 331       The current query context.
 332     </PARAM>
 333     <PARAM name="name" type="const SXP_char*">
 334       The name of the variable.
 335     </PARAM>
 336     <PARAM name="value" type="double">
 337       The number to bind the variable to.
 338     </PARAM>
 339     <PARAM name="(RET)" type="int">
 340       The error code.
 341     </PARAM>
 342   </SYNTAX>
 343   <DESCRIPTION>
 344     Binds a variable to a number. The binding will only be in effect for the
 345     next <C>SXP_query</C>.
 346   </DESCRIPTION>
 347   <SEEALSO value="SXP_addVariableBinding"/>
 348   <SEEALSO value="SXP_addVariableString"/>
 349   <SEEALSO value="SXP_addVariableBoolean"/>
 350 </ENTRY>
 351
 352 <ENTRY id="SXP_addVariableString">
 353   <TYPE value="Functions"/>
 354   <SYNTAX>
 355     SXP_addVariableString(Q, name, value)
 356     <PARAM name="Q" type="QueryContext">
 357       The current query context.
 358     </PARAM>
 359     <PARAM name="name" type="const SXP_char*">
 360       The name of the variable.
 361     </PARAM>
 362     <PARAM name="value" type="const SXP_char*">
 363       The string to bind the variable to.
 364     </PARAM>
 365     <PARAM name="(RET)" type="int">
 366       The error code.
 367     </PARAM>
 368   </SYNTAX>
 369   <DESCRIPTION>
 370     Binds a variable to a string. The binding will only be in effect for the
 371     next <C>SXP_query</C>.
 372   </DESCRIPTION>
 373   <SEEALSO value="SXP_addVariableBinding"/>
 374   <SEEALSO value="SXP_addVariableNumber"/>
 375   <SEEALSO value="SXP_addVariableBoolean"/>
 376 </ENTRY>
 377
 378 <ENTRY id="SXP_addVariableBoolean">
 379   <TYPE value="Functions"/>
 380   <SYNTAX>
 381     SXP_addVariableBoolean(Q, name, value)
 382     <PARAM name="Q" type="QueryContext">
 383       The current query context.
 384     </PARAM>
 385     <PARAM name="name" type="const SXP_char*">
 386       The name of the variable.
 387     </PARAM>
 388     <PARAM name="value" type="int">
 389       The boolean value to bind the variable to.
 390     </PARAM>
 391     <PARAM name="(RET)" type="int">
 392       The error code.
 393     </PARAM>
 394   </SYNTAX>
 395   <DESCRIPTION>
 396     Binds a variable to a boolean. The binding will only be in effect for the
 397     next <C>SXP_query</C>.
 398   </DESCRIPTION>
 399   <SEEALSO value="SXP_addVariableBinding"/>
 400   <SEEALSO value="SXP_addVariableString"/>
 401   <SEEALSO value="SXP_addVariableNumber"/>
 402 </ENTRY>
 403
 404 <ENTRY id="SXP_addNamespaceDeclaration">
 405   <TYPE value="Functions"/>
 406   <SYNTAX>
 407     SXP_addNamespaceDeclaration(Q, prefix, uri)
 408     <PARAM name="Q" type="QueryContext">
 409       The current query context.
 410     </PARAM>
 411     <PARAM name="prefix" type="const SXP_char*">
 412       The namespace prefix.
 413     </PARAM>
 414     <PARAM name="uri" type="const SXP_char*">
 415       The namespace URI.
 416     </PARAM>
 417     <PARAM name="(RET)" type="int">
 418       The error code.
 419     </PARAM>
 420   </SYNTAX>
 421   <DESCRIPTION>
 422     Declares a new namespace with the given prefix and URI. The
 423     declaration will only be in effect for the next <C>SXP_query</C>.
 424   </DESCRIPTION>
 425   <SEEALSO value="SXP_addVariableBinding"/>
 426 </ENTRY>
 427
 428 <ENTRY id="SXP_query">
 429   <TYPE value="Functions"/>
 430   <SYNTAX>
 431     SXP_query(Q, query, node, position, size)
 432     <PARAM name="Q" type="QueryContext">
 433       The current query context.
 434     </PARAM>
 435     <PARAM name="query" type="const SXP_char*">
 436       The text of the query.
 437     </PARAM>
 438     <PARAM name="node" type="SXP_Node">
 439       The current node for the query.
 440     </PARAM>
 441     <PARAM name="position" type="int">
 442       The position of the current node in the evaluation context. As SXP
 443       is a C interface, the position is zero-based (unlike one-based
 444       XPath nodesets). Thus, you must set this parameter to 0 if you want
 445       the "position()" query to return 1.
 446     </PARAM>
 447     <PARAM name="size" type="int">
 448       The size of the evaluation context.
 449     </PARAM>
 450     <PARAM name="(RET)" type="int">
 451       The error code.
 452     </PARAM>
 453   </SYNTAX>
 454   <DESCRIPTION>
 455     Evaluates a query (given as text) based on the current node, the
 456     context position (zero-based) and the context size. Any namespaces
 457     declared using <C>SXP_addNamespaceDeclaration</C> are used for the
 458     evaluation, as are the variable bindings made using functions like
 459     <C>SXP_addVariableString</C>. Upon completion of the query, the
 460     pending namespace declarations and variable bindings are <B>cleared</B>.
 461   </DESCRIPTION>
 462   <EXAMPLE>
 463         SXP_query(Q, "node[1]/@att", root, 0, 1);
 464   </EXAMPLE>
 465   <SEEALSO value="SXP_getResultString"/>
 466   <SEEALSO value="SXP_getResultType"/>
 467 </ENTRY>
 468
 469 <ENTRY id="SXP_getResultType">
 470   <TYPE value="Functions"/>
 471   <SYNTAX>
 472     SXP_getResultType(Q, typePtr)
 473     <PARAM name="Q" type="QueryContext">
 474       The current query context.
 475     </PARAM>
 476     <PARAM name="typePtr" type="SXP_ExpressionType*">
 477       The pointer to store the result type at.
 478     </PARAM>
 479     <PARAM name="(RET)" type="int">
 480       The error code.
 481     </PARAM>
 482   </SYNTAX>
 483   <DESCRIPTION>
 484     Retrieves the type of a result expression (<C>SXP_ExpressionType</C>) held in
 485     <C>QueryContext</C> after <C>SXP_query</C> has been called.
 486   </DESCRIPTION>
 487   <SEEALSO value="SXP_getResultNumber"/>
 488   <SEEALSO value="SXP_getResultBool"/>
 489   <SEEALSO value="SXP_getResultString"/>
 490   <SEEALSO value="SXP_getResultNodeset"/>
 491 </ENTRY>
 492
 493 <ENTRY id="SXP_getResultNumber">
 494   <TYPE value="Functions"/>
 495   <SYNTAX>
 496     SXP_getResultNumber(Q, resultPtr)
 497     <PARAM name="Q" type="QueryContext">
 498       The current query context.
 499     </PARAM>
 500     <PARAM name="resultPtr" type="double*">
 501       The pointer to store the result at.
 502     </PARAM>
 503     <PARAM name="(RET)" type="int">
 504       The error code.
 505     </PARAM>
 506   </SYNTAX>
 507   <DESCRIPTION>
 508     Retrieves the result of a <C>SXP_query</C> as a double, performing
 509     a type conversion if necessary.
 510   </DESCRIPTION>
 511   <SEEALSO value="SXP_getResultBool"/>
 512   <SEEALSO value="SXP_getResultString"/>
 513   <SEEALSO value="SXP_getResultNodeset"/>
 514   <SEEALSO value="SXP_getResultType"/>
 515 </ENTRY>
 516
 517 <ENTRY id="SXP_getResultBool">
 518   <TYPE value="Functions"/>
 519   <SYNTAX>
 520     SXP_getResultBool(Q, resultPtr)
 521     <PARAM name="Q" type="QueryContext">
 522       The current query context.
 523     </PARAM>
 524     <PARAM name="resultPtr" type="int*">
 525       The pointer to store the result at.
 526     </PARAM>
 527     <PARAM name="(RET)" type="int">
 528       The error code.
 529     </PARAM>
 530   </SYNTAX>
 531   <DESCRIPTION>
 532     Retrieves the result of a <C>SXP_query</C> as a boolean, performing
 533     a type conversion if necessary.
 534   </DESCRIPTION>
 535   <SEEALSO value="SXP_getResultNumber"/>
 536   <SEEALSO value="SXP_getResultString"/>
 537   <SEEALSO value="SXP_getResultNodeset"/>
 538   <SEEALSO value="SXP_getResultType"/>
 539 </ENTRY>
 540
 541 <ENTRY id="SXP_getResultString">
 542   <TYPE value="Functions"/>
 543   <SYNTAX>
 544     SXP_getResultString(Q, resultPtr)
 545     <PARAM name="Q" type="QueryContext">
 546       The current query context.
 547     </PARAM>
 548     <PARAM name="resultPtr" type="const char**">
 549       The pointer to store the result at.
 550     </PARAM>
 551     <PARAM name="(RET)" type="int">
 552       The error code.
 553     </PARAM>
 554   </SYNTAX>
 555   <DESCRIPTION>
 556     Retrieves the result of a <C>SXP_query</C> as a string, performing
 557     a type conversion if necessary.
 558   </DESCRIPTION>
 559   <SEEALSO value="SXP_getResultNumber"/>
 560   <SEEALSO value="SXP_getResultBool"/>
 561   <SEEALSO value="SXP_getResultNodeset"/>
 562   <SEEALSO value="SXP_getResultType"/>
 563 </ENTRY>
 564
 565 <ENTRY id="SXP_getResultNodeset">
 566   <TYPE value="Functions"/>
 567   <SYNTAX>
 568     SXP_getResultNodeset(Q, resultPtr)
 569     <PARAM name="Q" type="QueryContext">
 570       The current query context.
 571     </PARAM>
 572     <PARAM name="resultPtr" type="SXP_NodeList*">
 573       The pointer to store the result at.
 574     </PARAM>
 575     <PARAM name="(RET)" type="int">
 576       The error code.
 577     </PARAM>
 578   </SYNTAX>
 579   <DESCRIPTION>
 580     Retrieves the result of a <C>SXP_query</C> as a nodeset. This can
 581     be subsequently manipulated using <C>SXP_getNodeListItem</C> and
 582     <C>SXP_getNodeListLength</C>. If the result is not of type
 583     nodeset, then XPath does not allow its conversion to a nodeset,
 584     and <C>SXP_ getResultNodeset</C> returns NULL in *resultPtr.
 585   </DESCRIPTION>
 586   <SEEALSO value="SXP_getResultNumber"/>
 587   <SEEALSO value="SXP_getResultBool"/>
 588   <SEEALSO value="SXP_getResultString"/>
 589   <SEEALSO value="SXP_getResultType"/>
 590 </ENTRY>
 591
 592 <ENTRY id="SXP_getNodeListLength">
 593   <TYPE value="Functions"/>
 594   <SYNTAX>
 595     SXP_getNodeListLength(list)
 596     <PARAM name="list" type="SXP_NodeList">
 597       A node list.
 598     </PARAM>
 599     <PARAM name="(RET)" type="int">
 600       The error code.
 601     </PARAM>
 602   </SYNTAX>
 603   <DESCRIPTION>
 604     Returns the number of items in a node list.
 605   </DESCRIPTION>
 606   <SEEALSO value="SXP_getNodeListItem"/>
 607 </ENTRY>
 608
 609 <ENTRY id="SXP_getNodeListItem">
 610   <TYPE value="Functions"/>
 611   <SYNTAX>
 612     SXP_getNodeListItem(list, index)
 613     <PARAM name="list" type="SXP_NodeList">
 614       A node list.
 615     </PARAM>
 616     <PARAM name="index" type="int">
 617       A zero-based index into the list.
 618     </PARAM>
 619     <PARAM name="(RET)" type="int">
 620       The error code.
 621     </PARAM>
 622   </SYNTAX>
 623   <DESCRIPTION>
 624     Returns the item at the given (zero-based) position in the node list.
 625   </DESCRIPTION>
 626   <SEEALSO value="SXP_getNodeListLength"/>
 627 </ENTRY>
 628
 629 <!--
 630
 631   Callbacks
 632
 633 -->
 634
 635 <ENTRY id="DOMHandler">
 636   <TYPE value="Callbacks"/>
 637   <DESCRIPTION>
 638     A structure holding the addresses of all the callback functions
 639     that reveal the DOM document to the SXP. It contains the following
 640     callbacks (in the given order):
 641
 642     &lt;ul>
 643     &lt;li> <C>getNodeType</C>,
 644     &lt;li> <C>getNodeName</C>,
 645     &lt;li> <C>getNodeNameURI</C>,
 646     &lt;li> <C>getNodeNameLocal</C>,
 647     &lt;li> <C>getNodeValue</C>,
 648     &lt;li> <C>getNextSibling</C>,
 649     &lt;li> <C>getPreviousSibling</C>,
 650     &lt;li> <C>getNextAttrNS</C>,
 651     &lt;li> <C>getPreviousAttrNS</C>,
 652     &lt;li> <C>getChildCount</C>,
 653     &lt;li> <C>getAttributeCount</C>,
 654     &lt;li> <C>getNamespaceCount</C>,
 655     &lt;li> <C>getChildNo</C>,
 656     &lt;li> <C>getAttributeNo</C>,
 657     &lt;li> <C>getNamespaceNo</C>,
 658     &lt;li> <C>getParent</C>,
 659     &lt;li> <C>getOwnerDocument</C>,
 660     &lt;li> <C>compareNodes</C>,
 661     &lt;li> <C>retrieveDocument</C>.
 662     &lt;/ul>
 663   </DESCRIPTION>
 664 </ENTRY>
 665
 666 <ENTRY id="getNodeType">
 667   <TYPE value="Callbacks"/>
 668   <SYNTAX>
 669     getNodeType(node)
 670     <PARAM name="node" type="SXP_Node">
 671       The node to operate on.
 672     </PARAM>
 673     <PARAM name="(RET)" type="SXP_NodeType">
 674       The type of the node.
 675     </PARAM>
 676   </SYNTAX>
 677   <DESCRIPTION>
 678     Returns the type of the given node, or SXP_NONE on error.
 679   </DESCRIPTION>
 680 </ENTRY>
 681
 682 <ENTRY id="getNodeName">
 683   <TYPE value="Callbacks"/>
 684   <SYNTAX>
 685     getNodeName(node)
 686     <PARAM name="node" type="SXP_Node">
 687       The node to operate on.
 688     </PARAM>
 689     <PARAM name="(RET)" type="const SXP_char*">
 690       The name of the node.
 691     </PARAM>
 692   </SYNTAX>
 693   <DESCRIPTION>
 694     Returns the qualified name of the given node (prefix:local-part). On error, returns NULL.
 695   </DESCRIPTION>
 696 </ENTRY>
 697
 698 <ENTRY id="getNodeNameURI">
 699   <TYPE value="Callbacks"/>
 700   <SYNTAX>
 701     getNodeNameURI(node)
 702     <PARAM name="node" type="SXP_Node">
 703       The node to operate on.
 704     </PARAM>
 705     <PARAM name="(RET)" type="const SXP_char*">
 706       The URI of the node's namespace.
 707     </PARAM>
 708   </SYNTAX>
 709   <DESCRIPTION>
 710     Returns the namespace URI of the given node. On error, returns NULL.
 711   </DESCRIPTION>
 712 </ENTRY>
 713
 714 <ENTRY id="getNodeNameLocal">
 715   <TYPE value="Callbacks"/>
 716   <SYNTAX>
 717     getNodeNameLocal(node)
 718     <PARAM name="node" type="SXP_Node">
 719       The node to operate on.
 720     </PARAM>
 721     <PARAM name="(RET)" type="const SXP_char*">
 722       The local name of the node.
 723     </PARAM>
 724   </SYNTAX>
 725   <DESCRIPTION>
 726     Returns the local part of the given node's name. On error, returns NULL.
 727   </DESCRIPTION>
 728 </ENTRY>
 729
 730 <ENTRY id="getNodeValue">
 731   <TYPE value="Callbacks"/>
 732   <SYNTAX>
 733     getNodeValue(node)
 734     <PARAM name="node" type="SXP_Node">
 735       The node to operate on.
 736     </PARAM>
 737     <PARAM name="(RET)" type="const SXP_char*">
 738       The value of the node.
 739     </PARAM>
 740   </SYNTAX>
 741   <DESCRIPTION>
 742     Returns the value of the given node, or NULL on error. The node
 743     values are as specified in the DOM Level 1 Core specification,
 744     with the addition that the value of a namespace node is the
 745     namespace URI.
 746   </DESCRIPTION>
 747 </ENTRY>
 748
 749 <ENTRY id="getNextSibling">
 750   <TYPE value="Callbacks"/>
 751   <SYNTAX>
 752     getNextSibling(node)
 753     <PARAM name="node" type="SXP_Node">
 754       The node to operate on.
 755     </PARAM>
 756     <PARAM name="(RET)" type="SXP_Node">
 757       The next sibling of the node.
 758     </PARAM>
 759   </SYNTAX>
 760   <DESCRIPTION>
 761     Returns the following sibling of the node, in document order. If
 762     there is no such sibling, returns NULL. If the node is an
 763     attribute or a namespace node, NULL is returned.
 764   </DESCRIPTION>
 765   <NOTE>
 766     In the early versions of the SXP, <C>getNextSibling</C> acted
 767     like <C>getNextAttrNS</C> when used on attributes and namespace
 768     nodes.
 769   </NOTE>
 770 </ENTRY>
 771
 772 <ENTRY id="getPreviousSibling">
 773   <TYPE value="Callbacks"/>
 774   <SYNTAX>
 775     getPreviousSibling(node)
 776     <PARAM name="node" type="SXP_Node">
 777       The node to operate on.
 778     </PARAM>
 779     <PARAM name="(RET)" type="SXP_Node">
 780       The preceding sibling of the node.
 781     </PARAM>
 782   </SYNTAX>
 783   <DESCRIPTION>
 784     Returns the preceding sibling of the node, in document order. If
 785     there is no such sibling, returns NULL. If the node is an
 786     attribute or a namespace node, NULL is returned.
 787   </DESCRIPTION>
 788   <NOTE>
 789     In the early versions of the SXP, <C>getPreviousSibling</C> acted
 790     like <C>getPreviousAttrNS</C> when used on attributes and namespace
 791     nodes.
 792   </NOTE>
 793 </ENTRY>
 794
 795 <ENTRY id="getNextAttrNS">
 796   <TYPE value="Callbacks"/>
 797   <SYNTAX>
 798     getNextAttrNS(node)
 799     <PARAM name="node" type="SXP_Node">
 800       The node to operate on.
 801     </PARAM>
 802     <PARAM name="(RET)" type="SXP_Node">
 803       The attribute/namespace node after the given one.
 804     </PARAM>
 805   </SYNTAX>
 806   <DESCRIPTION>
 807     If the given node is an attribute, the following attribute is
 808     returned; if it is a namespace node, the following namespace node
 809     is returned. If the node is not of these two types, or if there is
 810     no following node of the same type, the callback returns NULL.
 811   </DESCRIPTION>
 812 </ENTRY>
 813
 814 <ENTRY id="getPreviousAttrNS">
 815   <TYPE value="Callbacks"/>
 816   <SYNTAX>
 817     getPreviousAttrNS(node)
 818     <PARAM name="node" type="SXP_Node">
 819       The node to operate on.
 820     </PARAM>
 821     <PARAM name="(RET)" type="SXP_Node">
 822       The attribute/namespace node preceding the given one.
 823     </PARAM>
 824   </SYNTAX>
 825   <DESCRIPTION>
 826     If the given node is an attribute, the preceding attribute is
 827     returned; if it is a namespace node, the preceding namespace node
 828     is returned. If the node is not of these two types, or if there is
 829     no preceding node of the same type, the callback returns NULL.
 830   </DESCRIPTION>
 831 </ENTRY>
 832
 833 <ENTRY id="getChildCount">
 834   <TYPE value="Callbacks"/>
 835   <SYNTAX>
 836     getChildCount(node)
 837     <PARAM name="node" type="SXP_Node">
 838       The node to operate on.
 839     </PARAM>
 840     <PARAM name="(RET)" type="int">
 841       The number of children of the node.
 842     </PARAM>
 843   </SYNTAX>
 844   <DESCRIPTION>
 845     Returns the number of children of the node. In particular, if the
 846     node is neither an element nor a document node, 0 is returned.
 847   </DESCRIPTION>
 848 </ENTRY>
 849
 850 <ENTRY id="getAttributeCount">
 851   <TYPE value="Callbacks"/>
 852   <SYNTAX>
 853     getAttributeCount(node)
 854     <PARAM name="node" type="SXP_Node">
 855       The node to operate on.
 856     </PARAM>
 857     <PARAM name="(RET)" type="int">
 858       The number of attributes of the node.
 859     </PARAM>
 860   </SYNTAX>
 861   <DESCRIPTION>
 862     Returns the number of attributes of the node. In particular, if the
 863     node is not an element, 0 is returned.
 864   </DESCRIPTION>
 865 </ENTRY>
 866
 867 <ENTRY id="getNamespaceCount">
 868   <TYPE value="Callbacks"/>
 869   <SYNTAX>
 870     getNamespaceCount(node)
 871     <PARAM name="node" type="SXP_Node">
 872       The node to operate on.
 873     </PARAM>
 874     <PARAM name="(RET)" type="int">
 875       The number of namespace declarations belonging to the node.
 876     </PARAM>
 877   </SYNTAX>
 878   <DESCRIPTION>
 879     Returns the number of namespace declarations belonging to the node. In particular, if the
 880     node is not an element, 0 is returned.
 881   </DESCRIPTION>
 882 </ENTRY>
 883
 884 <ENTRY id="getChildNo">
 885   <TYPE value="Callbacks"/>
 886   <SYNTAX>
 887     getChildNo(node, index)
 888     <PARAM name="node" type="SXP_Node">
 889       The node to operate on.
 890     </PARAM>
 891     <PARAM name="index" type="int">
 892       Index of a child.
 893     </PARAM>
 894     <PARAM name="(RET)" type="SXP_Node">
 895       The node's child with the given index.
 896     </PARAM>
 897   </SYNTAX>
 898   <DESCRIPTION>
 899     Returns the node's child at the given index. If the index is
 900     out of bounds, or if the node has no children, NULL is returned.
 901   </DESCRIPTION>
 902 </ENTRY>
 903
 904 <ENTRY id="getAttributeNo">
 905   <TYPE value="Callbacks"/>
 906   <SYNTAX>
 907     getAttributeNo(node, index)
 908     <PARAM name="node" type="SXP_Node">
 909       The node to operate on.
 910     </PARAM>
 911     <PARAM name="index" type="int">
 912       Index of an attribute.
 913     </PARAM>
 914     <PARAM name="(RET)" type="SXP_Node">
 915       The node's attribute with the given index.
 916     </PARAM>
 917   </SYNTAX>
 918   <DESCRIPTION>
 919     Returns the node's attribute at the given index. If the index is
 920     out of bounds, or if the node has no attributes, NULL is returned.
 921   </DESCRIPTION>
 922 </ENTRY>
 923
 924 <ENTRY id="getNamespaceNo">
 925   <TYPE value="Callbacks"/>
 926   <SYNTAX>
 927     getNamespaceNo(node, index)
 928     <PARAM name="node" type="SXP_Node">
 929       The node to operate on.
 930     </PARAM>
 931     <PARAM name="index" type="int">
 932       Index of a namespace node.
 933     </PARAM>
 934     <PARAM name="(RET)" type="SXP_Node">
 935       The namespace node with the given index among those belonging
 936       to the given node.
 937     </PARAM>
 938   </SYNTAX>
 939   <DESCRIPTION>
 940     Returns the namespace node which appears at the given position
 941     among those belonging to the given node. If the index is
 942     out of bounds, or if the node has no namespace nodes, NULL is returned.
 943   </DESCRIPTION>
 944 </ENTRY>
 945
 946 <ENTRY id="getParent">
 947   <TYPE value="Callbacks"/>
 948   <SYNTAX>
 949     getParent(node)
 950     <PARAM name="node" type="SXP_Node">
 951       The node to operate on.
 952     </PARAM>
 953     <PARAM name="(RET)" type="SXP_Node">
 954       The node's parent.
 955     </PARAM>
 956   </SYNTAX>
 957   <DESCRIPTION>
 958     Returns the given node's parent. If the node has no parent
 959       (i.e. is a SXP_Document), NULL is returned.
 960   </DESCRIPTION>
 961 </ENTRY>
 962
 963 <ENTRY id="getOwnerDocument">
 964   <TYPE value="Callbacks"/>
 965   <SYNTAX>
 966     getOwnerDocument(node)
 967     <PARAM name="node" type="SXP_Node">
 968       The node to operate on.
 969     </PARAM>
 970     <PARAM name="(RET)" type="SXP_Document">
 971       The owner document.
 972     </PARAM>
 973   </SYNTAX>
 974   <DESCRIPTION>
 975     Returns the given node's owner document.
 976   </DESCRIPTION>
 977 </ENTRY>
 978
 979 <ENTRY id="compareNodes">
 980   <TYPE value="Callbacks"/>
 981   <SYNTAX>
 982     compareNodes(node1,node2)
 983     <PARAM name="node1" type="SXP_Node">
 984       The first node to be compared.
 985     </PARAM>
 986     <PARAM name="node2" type="SXP_Node">
 987       The second node to be compared.
 988     </PARAM>
 989     <PARAM name="(RET)" type="int">
 990       The result of the comparison.
 991     </PARAM>
 992   </SYNTAX>
 993   <DESCRIPTION>
 994     Compares two nodes based on the document order. Returns -1 if
 995     node1 &lt; node2 in this order, +1 if node1 &gt; node2, and 0 if
 996     the nodes are identical. Any other value signifies an error.
 997   </DESCRIPTION>
 998 </ENTRY>
 999
1000 <ENTRY id="retrieveDocument">
1001   <TYPE value="Callbacks"/>
1002   <SYNTAX>
1003     retrieveDocument(uri)
1004     <PARAM name="uri" type="const SXP_char*">
1005       The URI of the document to be retrieved.
1006     </PARAM>
1007     <PARAM name="(RET)" type="SXP_Document">
1008       The retrieved document.
1009     </PARAM>
1010   </SYNTAX>
1011   <DESCRIPTION>
1012     Returns the document found at the given URI. If the document could
1013     not be retrieved, NULL is returned.
1014   </DESCRIPTION>
1015 </ENTRY>
1016
1017 </API>
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028