diff options
Diffstat (limited to 'doc/iksemel.texi')
| -rw-r--r-- | doc/iksemel.texi | 1534 |
1 files changed, 1534 insertions, 0 deletions
diff --git a/doc/iksemel.texi b/doc/iksemel.texi new file mode 100644 index 0000000..fd683e2 --- /dev/null +++ b/doc/iksemel.texi @@ -0,0 +1,1534 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename iksemel +@setcontentsaftertitlepage +@settitle Iksemel Programmers Manual +@set VERSION 1.2 +@c %**end of header + +@titlepage +@title iksemel programmers manual +@subtitle A tutorial and API reference for the iksemel library @value{VERSION} +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 2001-2003 G@"urer @"Ozen + +This is a free document; you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation; either version 2, or +(at your option) any later version.You may obtain a copy of the +GNU General Public License from the Free Software Foundation +by visiting their Web site or by writing to the Free Software +Foundation, Inc., 59 Temple Place - Suite 330, Boston, +MA 02111-1307, USA. + +@end titlepage + +@ifinfo +@node Top, , , (dir) +@top iksemel Programmers Manual + +Copyright @copyright{} 2001-2003 G@"urer @"Ozen + +This is a free document; you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation; either version 2, or +(at your option) any later version.You may obtain a copy of the +GNU General Public License from the Free Software Foundation +by visiting their Web site or by writing to the Free Software +Foundation, Inc., 59 Temple Place - Suite 330, Boston, +MA 02111-1307, USA. + +@menu +* Introduction:: + +* Tutorials:: + +* Development:: + +* Datatype Index:: + +* Function Index:: +@end menu +@end ifinfo + +@node Introduction, Tutorials, ,Top +@chapter Introduction + +iksemel is an XML (eXtensible Markup Language) parser library +designed for Jabber applications. It is coded in ANSI C for POSIX +compatible environments, thus highly portable. It is free software +released under the GNU Lesser General Public License. + +The purprose of this manual is to tell you how to use the facilities +of the iksemel library. Manual is written with the assumption that you +are familiar with the C programming language, basic programming +concepts, XML and Jabber protocol. + +@section Compiling the Library + +You need to install MinGW (@url{http://mingw.org}) under Windows to be able +to compile iksemel. Although not tested by the author, Cygwin should +work equally well. + +Library can be built with: + +@example +./configure +make +@end example + +If you want to make a self test: + +@example +make test +@end example + +Now you can install it with: + +@example +make install +@end example + + +@section Using iksemel in Applications + +You need to include @file{iksemel.h} file in your source to access library API. +You can do this with: + +@code{#include "iksemel.h"} + +Now you can use iksemel functions and compile your source. In able to link +your compiled object files and generate your executable program, you have to +link with iksemel library. This can be done with: + +@example +gcc -o myprg src1.o src2.o src3.o -liksemel +@end example + +iksemel registers itself with pkg-config while installing, so if you are using +autotools in your program, you can simply check the availability of iksemel +and configure your build process accordingly with: + +@example +PKG_CHECK_MODULES(IKSEMEL,iksemel,,exit) +@end example + +This would result in IKSEMEL_LIBS and IKSEMEL_CFLAGS substitution variables +set to correct values. + +@node Tutorials,Development,Introduction,Top +@chapter Tutorials + +@ifinfo +@menu +* Parsing an XML Document:: + +* Working with XML Trees:: + +* XML Streams:: + +* Writing a Jabber Client:: + +* Utility Functions:: +@end menu +@end ifinfo + + +@comment ============================================================ +@node Parsing an XML Document,Working with XML Trees,,Tutorials +@section Parsing an XML Document + +iksemel parser sequentally processes the XML document. Each encountered XML +element (i.e. tags, character data, comments, processing instructions, etc.) +is reported to your application by calling the hook functions you have provided. +This type of interface is called SAX (serial access) interface. + +@tindex iksparser +Parser stores its state in a small structure. This structure is referenced by +@code{iksparser} type, and managed with following functions: + +@deftypefun iksparser* iks_sax_new (void* @var{user_data}, iksTagHook* @var{tagHook}, iksCDataHook* @var{cdataHook}); +This function allocates and initializes a parser structure. If allocation fails, +NULL value is returned. @var{user_data} is passed directly to hook functions. +@end deftypefun + +@deftp Typedef iksTagHook +int iksTagHook (void* @var{user_data}, char* @var{name}, char** @var{atts}, int @var{type}); + +This function is called when a tag parsed. @var{name} is the name of the tag. If tag has +no attributes @var{atts} is NULL, otherwise it contains a null terminated list of +pointers to tag's attributes and their values. If return value isn't @code{IKS_OK}, +it is passed immediately to the caller of the @code{iks_parse}. + +@var{type} is one of the following: +@table @code +@item IKS_OPEN +Opening tag, i.e. <tag attr='value'> +@item IKS_CLOSE +Closing tag, i.e. </tag> +@item IKS_SINGLE +Standalone tag, i.e. <tag attr='value'/> +@end table +@end deftp + +@deftp Typedef iksCDataHook +int iksCDataHook (void* @var{user_data}, char* @var{data}, size_t @var{len}); + +@var{data} is a pointer to the character data. Encoding is UTF-8 and it isn't terminated +with a null character. Size of the data is given with @var{len} in bytes. This function +can be called several times with smaller sized data for a single string. If +return value isn't @code{IKS_OK}, it is passed immediately to the caller of the +@code{iks_parse}. +@end deftp + +@deftypefun int iks_parse (iksparser* @var{prs}, char *@var{data}, size_t @var{len}, int @var{finish}); +You give XML document to the parser with this function. @var{data} +is a @var{len} bytes string. If @var{len} is zero, data must be a null +terminated string. + +If @var{finish} value is zero, parser waits for more data later. If you +want to finish parsing without giving data, call it like: +@example +iks_parse (my_parser, NULL, 0, 1); +@end example + +You should check the return value for following conditions: +@table @code +@item IKS_OK +There isn't any problem. +@item IKS_NOMEM +Not enough memory. +@item IKS_BADXML +Document is not well-formed. +@item IKS_HOOK +Your hook decided that there is an error. +@end table +@end deftypefun + +@deftypefun void iks_parser_delete (iksparser* @var{prs}); +This function frees parser structure and associated data. +@end deftypefun + +Now we have learned how to create and use a sax parser. Lets parse a simple +XML document. Write following code into a @file{test.c} file. + +@smallexample +#include <stdio.h> +#include <iksemel.h> + +int pr_tag (void *udata, char *name, char **atts, int type) +@{ + switch (type) @{ + case IKS_OPEN: + printf ("TAG <%s>\n", name); + break; + case IKS_CLOSE: + printf ("TAG </%s>\n", name); + break; + case IKS_SINGLE: + printf ("TAG <%s/>\n", name); + break; + @} + if (atts) @{ + int i = 0; + while (atts[i]) @{ + printf (" ATTRIB %s='%s'\n", atts[i], atts[i+1]); + i += 2; + @} + @} + return IKS_OK; +@} + +enum ikserror pr_cdata (void *udata, char *data, size_t len) +@{ + int i; + printf ("CDATA ["); + for (i = 0; i < len; i++) + putchar (data[i]); + printf ("]\n"); + return IKS_OK; +@} + +int main (int argc, char *argv[]) +@{ + iksparser *p; + p = iks_sax_new (NULL, pr_tag, pr_cdata); + switch (iks_parse (p, argv[1], 0, 1)) @{ + case IKS_OK: + puts ("OK"); + break; + case IKS_NOMEM: + puts ("Not enough memory"); + exit (1); + case IKS_BADXML: + puts ("XML document is not well-formed"); + exit (2); + case IKS_HOOK: + puts ("Our hooks didn't like something"); + exit (2); + @} + iks_parser_delete (p); + return 0; +@} +@end smallexample + +Now compile and test it with: + +@example +gcc -o test test.c -liksemel +./test "<test>Hello<br/>World!</test>" +./test "<lala a='12' b='42'/>" +@end example + +@heading Error Handling + +XML standart states that once an error is detected, the processor must not continue +normal processing (i.e. it must not pass character data or markup information to +the application). So iksemel stops processing immediately when it encounters a +syntax error, or one of your hook functions return any one value than @code{IKS_OK}, +and @code{iks_parse} function returns with the error code. + +Since it is useful for debugging, iksemel provides functions to get position of +the error. Position is usually at the starting character for syntax errors. Since +your hooks are called after whole element (i.e. markup or character data) is +passed, position is at the end of the erroneous element for @code{IKS_HOOK} errors. + +@deftypefun {unsigned long} iks_nr_bytes (iksparser* @var{prs}); +Returns how many number of bytes parsed. +@end deftypefun + +@deftypefun {unsigned long} iks_nr_lines (iksparser* @var{prs}); +Returns how many number of lines parsed. +@end deftypefun + +If you want to parse another document with your parser again, you should use +the following function to reset your parser. + +@deftypefun void iks_parser_reset (iksparser* @var{prs}); +Resets the parser's internal state. +@end deftypefun + + +@comment ============================================================ +@node Working with XML Trees,XML Streams,Parsing an XML Document,Tutorials +@section Working with XML Trees + +SAX interface uses very little memory, but it forces you to access XML +documents sequentally. In many cases you want to keep a tree like +representation of XML document in memory and want to access and +modify its content randomly. + +iksemel provides functions for efficiently creating such trees either +from documents or programmaticaly. You can access and modify this +tree and can easily generate a new XML document from the tree. + +This is called DOM (Document Object Model) interface. + +@ifinfo +@menu +* Memory Management:: + +* Creating a Tree:: + +* Accessing the Tree:: + +* Converting a Tree into an XML Document:: + +* Parsing an XML Document into a Tree:: +@end menu +@end ifinfo + + +@comment ============================================================ +@node Memory Management,Creating a Tree,,Working with XML Trees +@subsection Memory Management + +Since keeping whole document content uses a lot of memory and requires +many calls to OS's memory allocation layer, iksemel uses a simple object +stack system for minimizing calls to the @code{malloc} function and releasing +all the memory associated with a tree in a single step. + +A parsed XML tree contains following objects: +@table @samp +@item Nodes +These are basic blocks of document. They can contain a tag, attribute pair +of a tag, or character data. Tag nodes can also contain other nodes as +children. Node structure has a small fixed size depending on the node type. +@item Names +Names of tags and attributes. They are utf-8 encoded small strings. +@item Character Data +They are similar to names but usually much bigger. +@end table + +iksemel's object stack has two separate areas for keeping these data objects. +Meta chunk contains all the structures and aligned data, while the data chunk +contains strings. Each chunk starts with a choosen size memory block, then +when necessary more blocks allocated for providing space. Unless there is a big +request, each block is double the size of the previous block, thus real memory +needs are quickly reached without allocating too many blocks, or wasting +memory with too big blocks. + +@deftp Typedef ikstack +This is a structure defining the object stack. Its fields are private +and subject to change with new iksemel releases. +@end deftp + +@deftypefun {ikstack *} iks_stack_new (size_t @var{meta_chunk}, size_t @var{data_chunk}); +Creates an object stack. @var{meta_chunk} is the initial size of the +data block used for structures and aligned data. @var{data_chunk} is +the initial size of the data block used for strings. They are both in byte units. + +These two initial chunks and a small object stack structure is allocated in +one @code{malloc} call for optimization purproses. +@end deftypefun + +@deftypefun {void *} iks_stack_alloc (ikstack * @var{stack}, size_t @var{size}); +Allocates @var{size} bytes of space from the object stack's meta chunk. +Allocated space is aligned on platform's default alignment boundary and +isn't initialized. Returns a pointer to the space, or NULL if there isn't enough +space available and allocating a new block fails. +@end deftypefun + +@deftypefun {void *} iks_stack_strdup (ikstack * @var{stack}, const char * @var{src}, size_t @var{len}); +Copies given string @var{src} into the object stack's data chunk. Returns a +pointer to the new string, or NULL if there isn't enough space in the stack. +If @var{len} is zero string must be null terminated. +@end deftypefun + +@deftypefun void iks_stack_delete (ikstack * @var{stack}); +Gives all memory associated with object stack to the system. +@end deftypefun + +Since character data sections are usually parsed in separate blocks, +a growable string implementation is necessary for saving memory. + +@deftypefun {char *} iks_stack_strcat (ikstack *@var{stack}, char *@var{old}, size_t @var{old_len}, const char *@var{src}, size_t @var{src_len}); +This function appends the string @var{src} to the string @var{old} in the +stack's data chunk. If @var{old} is NULL it behaves like @code{iks_stack_strdup}. +Otherwise @var{old} has to be a string created with @code{iks_stack_strdup} +or @code{iks_stack_strcat} functions. + +If @var{old_len} or @var{src_len} is zero, corresponding string must be null +terminated. + +Since string can be moved into another block of the data chunk, you must use the +returned value for new string, and must not reference to @var{old} anymore. +Return value can be NULL if there isn't enough space in stack, and allocating a +new block fails. +@end deftypefun + + +@comment ============================================================ +@node Creating a Tree,Accessing the Tree,Memory Management,Working with XML Trees +@subsection Creating a Tree + +@deftp Typedef iks +This is a structure defining a XML node. Its fields are private and only +accessed by following functions. +@end deftp + +@deftypefun iks* iks_new (const char *@var{name}); +Creates an object stack and creates a IKS_TAG type of node with given +tag name inside the stack. Tag name is also copied into the stack. +Returns the node pointer, or NULL if there isn't enough memory. +@end deftypefun + +@deftypefun iks* iks_new_within (const char *@var{name}, ikstack* @var{stack}); +Creates a IKS_TAG type of node with the given tag name. Node and tag +name is allocated inside the given object stack. Returns the node +pointer, or NULL if there isn't enough memory. +@end deftypefun + +@deftypefun iks* iks_insert (iks *@var{x}, const char *@var{name}); +Creates a IKS_TAG type of node with the given tag name. Node and tag +name is allocated inside the @var{x} node's object stack and linked +to @var{x} as a child node. Returns the node pointer, or NULL if there +isn't enough memory. +@end deftypefun + +@deftypefun iks* iks_insert_cdata (iks* @var{x}, const char* @var{data}, size_t @var{len}); +Creates a IKS_CDATA type of node with given character data. Node is +allocated inside the @var{x} node's object stack and linked to @var{x} +as a child node. Data is copied as well. If @var{len} is zero data must +be a null terminated string. Returns the node pointer, or NULL if +there isn't enough memory. +@end deftypefun + +@deftypefun iks* iks_insert_attrib (iks* @var{x}, const char* @var{name}, const char* @var{value}); +Creates a IKS_ATTRIBUTE type of node with given attribute name and the +value. Node is allocated inside the @var{x} node's object stack and +linked to @var{x} as an attribute node. Attribute name and value is +copied as well. Returns the node pointer, or NULL if there isn't +enough memory. + +Reinserting another value with same attribute name changes an attribute's +value. If @var{value} is NULL, attribute is removed from the tag. +@end deftypefun + +@deftypefun iks* iks_insert_node (iks* @var{x}, iks* @var{y}); +Links node @var{y} to node @var{x} as a child node. Nodes are not copied +between object stacks, be careful. +@end deftypefun + +@deftypefun void iks_hide (iks *@var{x}); +Changes the links of the other nodes so that @var{x} becomes invisible. +It stays in the same object stack with neighbour nodes, be careful. +@end deftypefun + +@deftypefun void iks_delete (iks *@var{x}); +Frees the object stack of the node @var{x}. +@end deftypefun + +Now lets create a tree representation of following XML document: + +@example +<message type='chat' from='bob@@bd.com'> +<subject>song lyric</subject><priority>high</priority> +<body> +<em style='underline'>here is the correct version:</em> +i just don't see why i should even care +it's not dark yet, but it's getting there +</body> +</message> +@end example + +here is the code: + +@example +iks *x, *y, *z; + +x = iks_new ("message"); +iks_insert_attrib (x, "type", "chat"); +iks_insert_attrib (x, "from", "bob@@bd.com"); +iks_insert_cdata (x, "\n", 1); +iks_insert_cdata (iks_insert (x, "subject"), "song lyric", 10); +iks_insert_cdata (iks_insert (x, "priority"), "high", 4); +iks_insert_cdata (x, "\n", 1); +y = iks_insert (x, "body"); +iks_insert_cdata (y, "\n", 1); +z = iks_insert (y, "em"); +iks_insert_attrib (z, "style", "underline"); +iks_insert_cdata (z, "here is the correct version", 0); +iks_insert_cdata (y, "\n", 1); +iks_insert_cdata (y, "i just don't see why", 0); +iks_insert_cdata (y, "i should even care\n", 0); +iks_insert_cdata (y, "it's not dark yet,", 0); +iks_insert_cdata (y, "but it's getting there\n", 0); +iks_insert_cdata (x, "\n", 1); +@end example + +Notice how newlines are inserted for proper formatting of document. They aren't +necessary for representing data, but they make it easier to read document for +humans. + +Also notice how @code{iks_insert} and @code{iks_insert_cdata} chained. + +There are also functions for duplicating xml trees. They are: + +@deftypefun {iks *} iks_copy (iks* @var{x}); +Creates a full copy of the tree in a newly created object stack. +@end deftypefun + +@deftypefun {iks *} iks_copy_within (iks* @var{x}, ikstack *@var{s}); +Creates a full copy of the tree in given object stack. +@end deftypefun + +@comment ============================================================ +@node Accessing the Tree,Converting a Tree into an XML Document,Creating a Tree,Working with XML Trees +@subsection Accessing a Tree + +Basic access functions allow you to move on the tree: + +@deftypefun iks* iks_next (iks* @var{x}); +@end deftypefun +@deftypefun iks* iks_prev (iks* @var{x}); +@end deftypefun +@deftypefun iks* iks_parent (iks* @var{x}); +@end deftypefun +@deftypefun iks* iks_child (iks* @var{x}); +@end deftypefun +@deftypefun iks* iks_attrib (iks* @var{x}); +@end deftypefun + +These functions return a pointer to the next, previous, parent, first child, +and first attribute node of the given node @var{x}. If that node doesn't +exist or @var{x} is NULL, a NULL value is returned. + +@deftypefun {iks *} iks_root (iks *@var{x}); +Returns the topmost parent node of the @var{x}. +@end deftypefun + +@deftypefun iks* iks_next_tag (iks* @var{x}); +@end deftypefun +@deftypefun iks* iks_prev_tag (iks* @var{x}); +@end deftypefun +@deftypefun iks* iks_first_tag (iks* @var{x}); +@end deftypefun + +These functions return a pointer to the next, previous, first child node +of the given node @var{x}. Only tag nodes are considered, other type +of the nodes are skipped. If such a node doesn't exist or @var{x} is NULL, +a NULL value is returned. + +Another group of functions allow you to access specific information and +content of the nodes: + +@deftypefun ikstack* iks_stack (iks* @var{x}); +Returns the object stack which node @var{x} stays. +@end deftypefun + +@deftypefun {enum ikstype} iks_type (iks* @var{x}); +Returns the type of the node. + +@tindex ikstype +@table @code +@item IKS_TAG +Node is a tag and can contain child nodes and attributes. +@item IKS_CDATA +Node contains character data. +@item IKS_ATTRIBUTE +Node contains an attribute and its value. +@end table +@end deftypefun + +@deftypefun char* iks_name (iks* @var{x}); +Returns the name of the tag for nodes with the type @var{IKS_TAG}. +Returns an attribute's name for nodes of type IKS_ATTRIBUTE. +@end deftypefun + +@deftypefun char* iks_cdata (iks* @var{x}); +Returns a pointer to node's character data if available, NULL otherwise. +Returns an attribute's value for nodes of type IKS_ATTRIBUTE. +@end deftypefun + +@deftypefun size_t iks_cdata_size (iks *@var{x}); +Returns the size of the node's character data in bytes. +@end deftypefun + +@deftypefun int iks_has_children (iks *@var{x}); +Returns a non-zero value if node @var{x} has a child node. +@end deftypefun + +@deftypefun int iks_has_attribs (iks *@var{x}); +Returns a non-zero value if node @var{x} has attributes. +@end deftypefun + +Last group of the functions simplifies finding and accessing the content +of a specific node: + +@deftypefun iks* iks_find (iks *@var{x}, const char *@var{name}); +Searches a IKS_TAG type of node with @var{name} as tag name in child +nodes of @var{x}. Returns a pointer to the node if found, NULL otherwise. +@end deftypefun + +@deftypefun char* iks_find_cdata (iks* @var{x}, const char* @var{name}); +Searches a IKS_TAG type of node with @var{name} as tag name in child +nodes of @var{x}. Returns a pointer to the character data of the node's +first child node if found, NULL otherwise. +@end deftypefun + +@deftypefun char* iks_find_attrib (iks* @var{x}, const char* @var{name}); +Searches an attribute with given name in attributes of the @var{x}. +Returns a pointer to attribute value if found, NULL otherwise. +@end deftypefun + +@deftypefun {iks *} iks_find_with_attrib (iks *@var{x}, const char *@var{tagname}, const char *@var{attrname}, const char *@var{value}); +Searches for a child tag of @var{x} which has an attribute with name +@var{attrname} and value @var{value}. If @var{tagname} isn't NULL, +name of the tag must also match. Returns a pointer to the node if found, +NULL otherwise. +@end deftypefun + +Here is an example which demonstrates accessing file names in a fictitious +XML playlist file: + +@example +<playlist> + <item type='mpg'> + <name>/home/madcat/download/matrix_rev_trailer.mpg</name> + <duration>1:17</duration> + </item> + <item type='rm'> + <name>/home/madcat/anim/clementine_ep1.rm</name> + <duration>22:00</duration> + </item> + <item type='avi'> + <name>/home/madcat/anim/futurama/ep101.avi</name> + <subtitle>/home/madcat/subs/futurama/ep101.txt</subtitle> + <duration>30:00</duration> + </item> + <repeat/> + <fullscreen/> + <noui/> +</playlist> +@end example + +and here is the code: + +@example +#include <stdio.h> +#include <iksemel.h> + +int main (int argc, char *argv[]) +@{ + iks *x, *y; + int e; + + if (argc < 2) @{ + printf ("usage: %s <playlistfile>", argv[0]); + return 0; + @} + e = iks_load (argv[1], &x); + if (e != IKS_OK) @{ + printf ("parse error %d\n", e); + return 1; + @} + if (iks_find (x, "repeat")) puts ("repeat mode enabled"); + y = iks_child (x); + while (y) @{ + if (iks_type (y) == IKS_TAG + && strcmp (iks_name (y), "item") == 0) @{ + printf ("Filename: [%s]\n", iks_find_cdata (y, "name")); + @} + y = iks_next (y); + @} + iks_delete (x); + return 0; +@} +@end example + + +@comment ============================================================ +@node Converting a Tree into an XML Document,Parsing an XML Document into a Tree,Accessing the Tree,Working with XML Trees +@subsection Converting a Tree to an XML Document + +There is a function for converting given XML tree into a null terminated string. + +@deftypefun {char *} iks_string (ikstack* @var{stack}, iks* @var{x}); +Converts given tree into a string. String is created inside the given object +stack. Returns a pointer to the string, or NULL if there isn't enough memory +available. + +If @var{stack} is NULL, string is created inside an @code{iks_malloc}ed buffer. +You can free it later with @code{iks_free} function. +@end deftypefun + +Here is an example which builds a tree and print it. + +@example +iks *x; +char *t; + +x = iks_new ("test"); +iks_insert_cdata (iks_insert (x, "a"), "1234", 4); +iks_insert (x, "br"); +iks_insert_cdata (x, "1234", 4); +t = iks_string (iks_stack (x), x); +puts (t); +iks_delete (x); +@end example + + +@comment ============================================================ +@node Parsing an XML Document into a Tree,,Converting a Tree into an XML Document,Working with XML Trees +@subsection Parsing a Document into a Tree + +If you want to automatically convert an XML document into a tree, you can use +iksemel's DOM parser. It is created with following function: + +@deftypefun iksparser* iks_dom_new (iks **@var{iksptr}); +Creates a DOM parser. A pointer to the created XML tree is put into the +variable pointed by @var{iksptr}. Returns a pointer to the parser, or NULL +is there isn't enough memory. +@end deftypefun + +Usage is same as SAX parser. You feed the data with @code{iks_parse}, and if +there isn't an error, you can access to your tree from variable @code{*iksptr}. + +Here is a simple example: + +@example +iks *x; +iksparser *p; + +p = iks_dom_new (&x); +if (IKS_OK != iks_parse (p, "<a>bcd</a>", 9, 1)) @{ + puts ("parse error"); +@} +/* x is useable after that point */ + +/* this will print 'bcd' */ +printf ("%s\n", iks_cdata (iks_child (x))); +@end example + +If you know the size of the file ahead, or you have an approximate idea, +you can tell this to the dom parser for choosing a better memory allocation +strategy. Here is the function for this. + +@deftypefun void iks_set_size_hint (iksparser *@var{prs}, size_t @var{approx_size}); +Parser @var{prs} must be a dom type parser. @var{approx_size} is the +expected size of the xml document. Parser chooses its chunk size +based on this information. Helps performance while processing big files. +@end deftypefun + +If you already have your XML document in memory, you can simply parse +it with: + +@deftypefun {iks *} iks_tree (const char *@var{xml_str}, size_t @var{len}, int *@var{err}); +This function parses the buffer pointed by @var{xml_str}. If @var{len} is zero +buffer is considered as a null terminated utf8 string. Returns the parsed tree, +or NULL if there is an error. If @var{err} is not NULL, actual error code (returned +by iks_parse) is put there. +@end deftypefun + +Most of the times you want to load your configuration (or similar) files directly +into trees. iksemel provides two functions to greatly simplify this: + +@deftypefun int iks_load (const char *@var{fname}, iks **@var{xptr}); +Loads the XML file. Tree is placed into the variable pointed by @var{xptr}. +@end deftypefun + +@deftypefun int iks_save (const char *@var{fname}, iks *@var{x}); +Converts tree @var{x} into a string and saves to the file. +@end deftypefun + +Both functions return same error codes as @code{iks_parse}. Some additional +error codes are defined for indicating file problems. They are: + +@table @code +@item IKS_FILE_NOFILE +A file with the given name doesn't exist. +@item IKS_FILE_NOACCESS +Cannot open file. Possibly a permission problem. +@item IKS_FILE_RWERR +Read or write operation failed. +@end table + +Here is a simple example which parses a file and saves it into another: + +@example +iks *x; + +if (IKS_OK != iks_load ("file1.xml", &x)) @{ + puts ("loading error"); +@} +if (IKS_OK != iks_save ("file2.xml", x)) @{ + puts ("saving error"); +@} +@end example + + +@comment ============================================================ +@node XML Streams,Writing a Jabber Client,Working with XML Trees,Tutorials +@section XML Streams + +XML streams function as containers for any XML chunks sent asynchronously +between network endpoints. They are used for asyncronously exchanging +relatively small payload of structured information between entities. + +A stream is initiated by one of hosts connecting to the other, and sending a +<stream:stream> tag. Receiving entity replies with a second XML stream +back to the initiating entity within the same connection. Each unit of +information is send as a direct child tag of the <stream:stream> tag. +Stream is closed with </stream:stream>. + +XML streams use a subset of XML. Specifically they should not contain +processing instructions, non-predefined entities, comments, or DTDs. + +Jabber protocol uses XML streams for exchanging messages, presence +information, and other information like authorization, search, time and +version queries, protocol extensions. + +iksemel provides you a stream parser, which automatically handles connection +to the server, and calls your hook function with incoming information +parsed and converted to an XML tree. + +You can create such a parser with: + +@deftypefun iksparser* iks_stream_new (char* @var{name_space}, void* @var{user_data}, iksStreamHook* @var{streamHook}); +Allocates and initalizes a stream parser. @var{name_space} indicates the +stream type, jabber clients use "jabber:client" namespace. @var{user_data} +is passed directly to your hook function. +@end deftypefun + +@deftp Typedef iksStreamHook +int iksStreamHook (void* @var{user_data}, int @var{type}, iks* @var{node}); + +Depending on the value of the @var{type}, @var{node} contains: +@table @code +@item IKS_NODE_START +Got the <stream:stream> tag, namespace, stream id and other information +is contained in the @var{node}. +@item IKS_NODE_NORMAL +A first level child of the <stream:stream> tag is received. @var{node} contains +the parsed tag. If you are connected to a jabber server, you can get <message>, +<presence>, or <iq> tags. +@item IKS_NODE_ERROR +Got a <stream:error> tag, details can be accessed from @var{node}. +@item IKS_NODE_STOP +</stream:stream> tag is received or connection is closed, @var{node} is @code{NULL}. +@end table + +Freeing the node with @code{iks_delete} is up to you. +@end deftp + +You can manually feed this parser with @code{iks_parse} function, but using +iksemel's connection facilities is easier for most of the cases. + +This functions return @code{IKS_OK} for success. Error codes of @code{iks_parse} +are used in same manner. Following additional codes are defined for +network related problems: + +@table @code +@item IKS_NET_NODNS +Hostname lookup failed. Possible reasons: hostname is incorrect, +you are not online, your dns server isn't accessible. +@item IKS_NET_NOSOCK +Socket cannot created. +@item IKS_NET_NOCONN +Connection attemp failed. Possible reasons: host is not an XML stream +server, port number is wrong, server is busy or closed for the moment. +@item IKS_NET_RWERR +@code{send} or @code{recv} call is failed when attempting to exchange +the data with the server. You should close the connection with @code{iks_disconnect} +after getting this error from data transfer functions. +@end table + +@deftypefun int iks_connect_tcp (iksparser *@var{prs}, const char *@var{server}, int @var{port}); +This function connects the parser to a server and sends stream header for you. +@var{server} is the host name of the server and @var{port} is the tcp port +number which server is listening to. You can use @code{IKS_JABBER_PORT} +macro for the default jabber client port (5222). +@end deftypefun + +@deftypefun int iks_connect_fd (iksparser *@var{prs}, int @var{fd}); +Attaches parser to an already opened connection. @var{fd} is the socket +descriptor. Note that @code{iks_disconnect} doesn't close the socket +for this kind of connection, opening and closing of the socket is up to your +application. Stream header is not sent automatically. You can use +@code{iks_send_header} function for sending it. +@end deftypefun + +@deftypefun void iks_disconnect (iksparser *@var{prs}); +Closes connection to the server, and frees connection resources. +@end deftypefun + +After successfully connecting to a server, you can use following functions +for exchanging information with server. + +@deftypefun int iks_recv (iksparser* @var{prs}, int @var{timeout}); +If @var{timeout} is @code{-1}, waits until some data arrives from server, +and process the data. Your stream hook can be called if a complete +chunk is arrived. + +If @var{timeout} is a positive integer, @code{iks_recv} returns if no data +arrives for @var{timeout} seconds. + +If @var{timeout} is zero, @code{iks_recv} checks if there is any data +waiting at the network buffer, and returns without waiting for data. +@end deftypefun + +@deftypefun int iks_fd (iksparser* @var{prs}); +Returns the file descriptor of the connected socket. You can use this in +your @code{select} function or some other input loop to act whenever +some data from the server arrives. This value of only valid between +a successful @code{iks_connect_tcp} and @code{iks_disconnect}. +@end deftypefun + +@deftypefun int iks_send (iksparser* @var{prs}, iks* @var{x}); +Converts the tree given in @var{x} to a string, and sends to the server. +String is created inside the object stack of @var{x}. +@end deftypefun + +@deftypefun int iks_send_raw (iksparser* @var{prs}, char* @var{xmlstr}); +Sends the string given in @var{xmlstr} to the server. +@end deftypefun + +@deftypefun int iks_send_header (iksparser *@var{prs}, char *@var{to}); +Sends the stream header. @var{to} is the name of the server. +Normally @code{iks_connect_tcp} function calls this for you. This +is only useful if you are using @code{iks_connect_fd}. +@end deftypefun + +Sometimes it is useful to log incoming and outgoing data to your parser +for debugging your applications. iksemel provides a logging facility for you. + +@deftypefun void iks_set_log_hook (iksparser* @var{prs}, iksLogHook* @var{logHook}); +Sets the log function for your stream parser. You can't use this function +on any other type of parser. +@end deftypefun + +@deftp Typedef iksLogHook +void iksLogHook (void* @var{user_data}, const char* @var{data}, size_t @var{size}, int @var{is_incoming}); + +@var{user_data} is same value which you give with @code{iks_stream_new}. +@var{data} is @var{size} bytes of data. Be very careful that this data may be +coming from other side of the connection and can contain malicius bytes. It isn't +checked by iksemel yet, so you should check it yourself before displaying or +passing to other systems in your application or computer. If @var{is_incoming} +is a non-zero value, data is incoming from server, otherwise it is outgoing to the +server. +@end deftp + + +@comment ============================================================ +@node Writing a Jabber Client,Utility Functions,XML Streams,Tutorials +@section Writing a Jabber Client + +@ifinfo +@menu +* Security:: + +* Packets:: + +* Packet Filter:: + +* Creating Common Packets:: + +@end menu +@end ifinfo + +@comment ============================================================ +@node Security,Packets,,Writing a Jabber Client +@subsection Security + +iksemel supports TLS protocol for encrypted communication and SASL +protocol for authentication. TLS is handled by gnutls library. + +@deftypefun int iks_has_tls (void); +If iksemel is compiled with gnutls library, this function returns a non-zero +value indicating you can try encrypted connection with the server. +@end deftypefun + +@deftypefun int iks_start_tls (iksparser* @var{prs}); +Starts a TLS handshake over already connected parser. Returns IKS_OK or +one of the IKS_NET_ errors. If handshake succeeds you'll get another +stream header from server. +@end deftypefun + +@deftypefun int iks_is_secure (iksparser* @var{prs}); +Returns a non-zero value if a secure connection is fully established +between server. +@end deftypefun + +@deftypefun int iks_start_sasl (iksparser* @var{prs}, enum ikssasltype @var{type}, char* @var{username}, char* @var{pass}); +Starts SASL operation. +@end deftypefun + +See tools/iksroster.c for a good example. + +@comment ============================================================ +@node Packets,Packet Filter,Security,Writing a Jabber Client +@subsection Packets + +iksemel can parse a jabber XML node and provide you a public packet +structure which contains information like node type and subtype, id, +namespace, sender's jabber id, etc. + +This handles a lot of node parsing for you. Packets are also used in +the packet filter subsystem. + +@deftypefun {ikspak *} iks_packet (iks *@var{x}); +Takes a node from stream and extracts information from it to a packet structure. +Structure is allocated inside the node's object stack. +@end deftypefun + +@tindex ikspak +@code{ikspak} structure has following fields: + +@table @code +@item iks *x; +This is a pointer to the node. +@item iksid *from; +Sender's jabber id in parsed form. See below for @code{iksid} structure. +@item iks *query; +A pointer to the <query> tag for IQ nodes. +@item char *ns; +Namespace of the content for IQ nodes. +@item char *id; +ID of the node. +@item enum ikspaktype type; +Type of the node. Possible types are: + +@table @code +@item IKS_PAK_NONE +Unknown node. +@item IKS_PAK_MESSAGE +Message node. +@item IKS_PAK_PRESENCE +Presence node with presence publishing operation. +@item IKS_PAK_S10N +Presence node with subscription operation. +@item IKS_PAK_IQ +IQ node. +@end table +@item enum iksubtype subtype; +Sub type of the node. Sub types for message nodes: + +@table @code +@item IKS_TYPE_NONE +A normal message. +@item IKS_TYPE_CHAT +Private chat message. +@item IKS_TYPE_GROUPCHAT +Multi user chat message. +@item IKS_TYPE_HEADLINE +Message from a news source. +@item IKS_TYPE_ERROR +Message error. +@end table + +Sub types for IQ nodes: + +@table @code +@item IKS_TYPE_GET +Asks for some information. +@item IKS_TYPE_SET +Request for changing information. +@item IKS_TYPE_RESULT +Reply to get and set requests. +@item IKS_TYPE_ERROR +IQ error. +@end table + +Sub types for subscription nodes: + +@table @code +@item IKS_TYPE_SUBSCRIBE, +Asks for subscribing to the presence. +@item IKS_TYPE_SUBSCRIBED, +Grants subscription. +@item IKS_TYPE_UNSUBSCRIBE, +Asks for unsubscribing to the presence. +@item IKS_TYPE_UNSUBSCRIBED, +Cancels subscription. +@item IKS_TYPE_ERROR +Presence error. +@end table + +Sub types for presence nodes: + +@table @code +@item IKS_TYPE_PROBE, +Asks presence status. +@item IKS_TYPE_AVAILABLE, +Publishes entity as available. More information can be found in @code{show} field. +@item IKS_TYPE_UNAVAILABLE +Publishes entity as unavailable. More information can be found in @code{show} field. +@end table +@item enum ikshowtype show; +Presence state for the presence nodes. + +@table @code +@item IKS_SHOW_UNAVAILABLE +Entity is unavailable. +@item IKS_SHOW_AVAILABLE +Entity is available. +@item IKS_SHOW_CHAT +Entity is free for chat. +@item IKS_SHOW_AWAY +Entity is away for a short time. +@item IKS_SHOW_XA +Entity is away for a long time. +@item IKS_SHOW_DND +Entity doesn't want to be disturbed. +@end table +@end table + +iksemel has two functions to parse and compare jabber IDs. + +@deftypefun {iksid *} iks_id_new (ikstack *@var{s}, const char *@var{jid}); +Parses a jabber id into its parts. @code{iksid} structure is created inside +the @var{s} object stack. +@end deftypefun + +@tindex iksid +@code{iksid} structure has following fields: + +@table @code +@item char *user; +User name. +@item char *server; +Server name. +@item char *resource; +Resource. +@item char *partial; +User name and server name. +@item char *full; +User name, server name and resource. +@end table + +You can access this fields and read their values. Comparing two parsed jabber +ids can be done with: + +@deftypefun int iks_id_cmp (iksid *@var{a}, iksid *@var{b}, int @var{parts}); +Compares @var{parts} of @var{a} and @var{b}. Part values are: + +@table @code +@item IKS_ID_USER +@item IKS_ID_SERVER +@item IKS_ID_RESOURCE +@end table + +@sp 1 +You can combine this values with @code{or} operator. Some common combinations +are predefined for you: + +@table @code +@item IKS_ID_PARTIAL +@code{IKS_ID_USER | IKS_ID_SERVER} +@item IKS_ID_FULL +@code{IKS_ID_USER | IKS_ID_SERVER | IKS_ID_RESOURCE} +@end table + +Return value is @code{0} for equality. If entities are not equal a combination of +part values showing different parts is returned. +@end deftypefun + + +@comment ============================================================ +@node Packet Filter,Creating Common Packets,Packets,Writing a Jabber Client +@subsection Packet Filter + +Packet filter handles routing incoming packets to related functions. + +@tindex iksfilter +@deftypefun {iksfilter *} iks_filter_new (void); +Creates a new packet filter. +@end deftypefun + +@deftypefun void iks_filter_packet (iksfilter *@var{f}, ikspak *@var{pak}); +Feeds the filter with given packet. Packet is compared to registered rules and +hook functions of the matching rules are called in most matched to least +matched order. +@end deftypefun + +@deftypefun void iks_filter_delete (iksfilter *@var{f}); +Frees filter and rules. +@end deftypefun + +Rules are created with following function: + +@tindex iksrule +@deftypefun {iksrule *} iks_filter_add_rule (iksfilter *@var{f}, iksFilterHook *@var{filterHook}, void *@var{user_data}, @dots{}); +Adds a rule to the filter @var{f}. @var{user_data} is passed directly to your +hook function @var{filterHook}. + +A rule consist of one or more type and value pairs. Possible types: +@table @code +@item IKS_RULE_ID +Compares @code{char *} value to packet ids. +@item IKS_RULE_FROM +Compares @code{char *} value to packet senders. +@item IKS_RULE_FROM_PARTIAL +Compares @code{char *} value to packet sender. Ignores resource part of jabber id. +@item IKS_RULE_NS +Compares @code{char *} value to namespace of iq packets. +@item IKS_RULE_TYPE +Compares @code{int} value to packet types. +@item IKS_RULE_SUBTYPE +Compares @code{int} value to packet sub types. +@item IKS_RULE_DONE +Terminates the rule pairs. +@end table +@end deftypefun + +Here is an example which creates a filter and adds three rules: +@example +iksfilter *f; + +f = iks_filter_new (); +iks_filter_add_rule (f, on_msg, NULL, + IKS_RULE_TYPE, IKS_PAK_MESSAGE, + IKS_RULE_DONE); +iks_filter_add_rule (f, on_auth_result, NULL, + IKS_RULE_TYPE, IKS_PAK_IQ, + IKS_RULE_SUBTYPE, IKS_TYPE_RESULT, + IKS_RULE_ID, "auth", + IKS_RULE_DONE); +iks_filter_add_rule (f, on_roster_push, NULL, + IKS_RULE_TYPE, IKS_PAK_IQ, + IKS_RULE_SUBTYPE, IKS_TYPE_SET, + IKS_RULE_NS, "jabber:iq:roster", + IKS_RULE_DONE); +@end example + +@deftp Typedef iksFilterHook +int iksFilterHook (void *user_data, ikspak *pak); + +Your hook is called with your @var{user_data} and matching packet @var{pak}. +You can return two different values from your hook: +@table @code +@item IKS_FILTER_PASS +Packet is forwarded to least matching rules. +@item IKS_FILTER_EAT +Filtering process for the packet ends. +@end table +@end deftp + +You can remove the rules with following functions: + +@deftypefun void iks_filter_remove_rule (iksfilter *@var{f}, iksrule *@var{rule}); +Removes the rule from filter. +@end deftypefun + +@deftypefun void iks_filter_remove_hook (iksfilter *@var{f}, iksFilterHook *@var{filterHook}); +Remove the rules using @var{filterHook} function from filter. +@end deftypefun + + +@comment ============================================================ +@node Creating Common Packets,,Packet Filter,Writing a Jabber Client +@subsection Creating Common Packets + +A usual jabber network traffic contains many similar XML constructs. iksemel +provides several utility functions for creating them. They all generate an XML +tree, so you can add or modify some parts of the tree, and send to server then. + +@deftypefun {iks *} iks_make_auth (iksid *@var{id}, const char *@var{pass}, const char *@var{sid}); +Creates an authorization packet. @var{id} is your parsed jabber id, and @var{pass} +is your password. + +If stream id @var{sid} isn't NULL, SHA1 authentication is used, otherwise password +is attached in plain text. You can learn stream id from @code{IKS_STREAM_START} +packet in your stream hook like this: + +@example +char *sid; + +if (type == IKS_STREAM_START) @{ + sid = iks_find_attrib (node, "id"); +@} +@end example +@end deftypefun + +@deftypefun {iks *} iks_make_msg (enum iksubtype @var{type}, const char *@var{to}, const char *@var{body}); +Creates a message packet. @var{type} is the message type, @var{to} is jabber id +of the recipient, @var{body} is the message. +@end deftypefun + +@deftypefun {iks *} iks_make_s10n (enum iksubtype @var{type}, const char *@var{to}, const char *@var{msg}); +Creates a presence packet for subscription operations. @var{type} is operation, +@var{to} is jabber id of the recipient, @var{msg} is a small message for +introducing yourself, or explaning the reason of why you are subscribing or +unsubscribing. +@end deftypefun + +@deftypefun {iks *} iks_make_pres (enum ikshowtype @var{show}, const char *@var{status}); +Creates a presence packet for publishing your presence. @var{show} is your +presence state and @var{status} is a message explaining why you are not +available at the moment, or what you are doing now. +@end deftypefun + +@deftypefun {iks *} iks_make_iq (enum iksubtype @var{type}, const char *@var{xmlns}); +Creates an IQ packet. @var{type} is operation type and @var{xmlns} is the +namespace of the content. You usually have to add real content to the <query> +tag before sending this packet. +@end deftypefun + + +@comment ============================================================ +@node Utility Functions,,Writing a Jabber Client,Tutorials +@section Utility Functions + +@subsection Memory Utilities + +@deftypefun {void *} iks_malloc (size_t @var{size}); +@end deftypefun +@deftypefun void iks_free (void *@var{ptr}); +@end deftypefun + +These are wrappers around ANSI malloc and free functions used by the +iksemel library itself. You can free the output of iks_string (only if you +passed it a NULL stack) with iks_free for example. That is important +if you are using a malloc debugger in your application but not in iksemel +or vice versa. + +@comment ============================================================ +@subsection String Utilities + +@deftypefun {char *} iks_strdup (const char *@var{src}); +@end deftypefun +@deftypefun int iks_strcmp (const char *@var{a}, const char *@var{b}); +@end deftypefun +@deftypefun int iks_strcasecmp (const char *@var{a}, const char *@var{b}); +@end deftypefun +@deftypefun int iks_strncmp (const char *@var{a}, const char *@var{b}, size_t @var{n}); +@end deftypefun +@deftypefun int iks_strncasecmp (const char *@var{a}, const char *@var{b}, size_t @var{n}); +@end deftypefun +@deftypefun size_t iks_strlen (const char *@var{src}); +@end deftypefun + +These functions work exactly like their ANSI equivalents except that they allow +NULL values for string pointers. If @var{src} is NULL, iks_strdup and iks_strlen +returns zero. If @var{a} or @var{b} is NULL in string comparisation functions +they return -1. + +Their usefulness comes from the fact that they can chained with DOM traversing +functions like this: + +@smallexample +if (iks_strcmp (iks_find_attrib (x, "id"), "x1") == 0) count++; +@end smallexample + +That example works even x doesn't have an 'id' attribute and iks_find_attrib +returns NULL. So you don't need to use temporary variables in such +situations. + +@comment ============================================================ +@subsection SHA1 Hash + +Secure Hash Algorithm (SHA1) is used in the Jabber authentication +protocol for encoding your password when sending to the server. +This is normally handled by iks_make_auth() function, but if you +want to handle it manually, or if you need a good hash function +for other purproses you can use these functions. + +@deftypefun iksha* iks_sha_new (void); +Allocates a structure for keeping calculation values and the state. +@end deftypefun + +@deftypefun void iks_sha_reset (iksha *@var{sha}); +Resets the state of the calculation. +@end deftypefun + +@deftypefun void iks_sha_hash (iksha *@var{sha}, const unsigned char *@var{data}, int @var{len}, int @var{finish}); +Calculates the hash value of the given data. If @var{finish} is non +zero, applies the last step of the calculation. +@end deftypefun + +@deftypefun void iks_sha_print (iksha *@var{sha}, char *@var{hash}); +Prints the result of a finished calculation into the buffer pointed by @var{hash} +in hexadecimal string form. Buffer must be at least 40 bytes long. String +is not null terminated. +@end deftypefun + +@deftypefun void iks_sha (const char *@var{data}, char *@var{hash}); +Calculates the hash value of @var{data} and prints into @var{hash}. +This is a helper function for simple hash calculations. It calls +other functions for the actual work. +@end deftypefun + + +@comment ============================================================ + + +@node Development,Datatype Index,Tutorials,Top +@chapter Development + +This chapter contains information on plan, procedure and standarts of +iksemel development. + +@section Roadmap + +There are three main functions iksemel tries to provide to applications: +@itemize @bullet +@item +A generic XML parser with SAX and DOM interfaces. +@item +XML stream client and server functionality. +@item +Utilities for Jabber clients. +@end itemize + +Goal of the iksemel is providing these functions while supporting embedded +environments, keeping usage simple, and having a robust implementation. + +Some decisions are made to reach this goal: + +Code is written in ANSI C with a single dependency on C library. Instead of +using expat or libxml, a simple built-in parser is used. Similarly glib and +gnu only features of glibc (like object stacks) are avoided and built-in +memory and string utilities are used. This may seem like code duplication +but since they are optimized for iksemel and only a few kb in size, +it isn't a big disadvantage. + +Code is placed files in a modular fashion, and different modules don't depend +on others' internal details. This allows taking unneeded functionality out when +building for low resource situations. + +It is tried to give functions names which are consistent, clear and short. + +API is documented with texinfo for high quality printed output and info file +output for fast and simple access during application development. Instead +of using an autogenerated system or simply listing function descriptions, +a task oriented tutorial approach is used. + +@section Coding Style + +Here is a short list describing preferred coding style for iksemel. +Please keep in mind when sending patches. + +@itemize @bullet +@item +Indentation is done with tabs. Aligning is done with spaces. +@item +Placement of braces is K&R style. +@item +Function names are put at the start of line. +@item +Function names are lowercase. +@item +Words of the function names are separated with underscore character. +@item +Structure and variable names are lowercase. +@item +Macro and enumarations names are uppercase. +@item +Exported library API is contained in the single iksemel.h file. +@item +Exported function names start with iks_ +@item +Exported structure and type names start with iks +@item +Exported macro and enumaration names start with IKS_ +@end itemize + +Here is an example: + +@smallexample +int +iks_new_func (char *text) +@{ + int i; + + i = an_internal_func (text); + if (IKS_SOME_VALUE == i) @{ + iks_some_func (text); + i++; + @} + return i; +@} +@end smallexample + +@section Resources + +@itemize @bullet +@item +RFC 2279, UTF-8 format @url{http://www.ietf.org/rfc/rfc2279.txt} +@item +W3C Recommendation, Extensible Markup Language 1.0 @url{http://www.w3.org/TR/REC-xml} +@item +Annotated XML Specification @url{http://www.xml.com/axml/testaxml.htm} +@item +Jabber Protocol Documents @url{http://www.jabber.org/protocol/} +@end itemize + + +@comment ============================================================ + + +@node Datatype Index,Function Index,Development,Top +@unnumbered Datatype Index +@printindex tp + + +@node Function Index,,Datatype Index,Top +@unnumbered Function Index +@printindex fn + + +@contents +@bye |