1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename iksemel.info 4@settitle Iksemel Programmers Manual 5@set VERSION 1.2 6@c %**end of header 7 8@titlepage 9@title iksemel programmers manual 10@subtitle A tutorial and API reference for the iksemel library @value{VERSION} 11@page 12@vskip 0pt plus 1filll 13Copyright @copyright{} 2001-2003 G@"urer @"Ozen 14 15This is a free document; you can redistribute it and/or 16modify it under the terms of the GNU General Public License as 17published by the Free Software Foundation; either version 2, or 18(at your option) any later version.You may obtain a copy of the 19GNU General Public License from the Free Software Foundation 20by visiting their Web site or by writing to the Free Software 21Foundation, Inc., 59 Temple Place - Suite 330, Boston, 22MA 02111-1307, USA. 23 24@end titlepage 25 26@ifinfo 27@node Top, , , (dir) 28@top iksemel Programmers Manual 29 30Copyright @copyright{} 2001-2003 G@"urer @"Ozen 31 32This is a free document; you can redistribute it and/or 33modify it under the terms of the GNU General Public License as 34published by the Free Software Foundation; either version 2, or 35(at your option) any later version.You may obtain a copy of the 36GNU General Public License from the Free Software Foundation 37by visiting their Web site or by writing to the Free Software 38Foundation, Inc., 59 Temple Place - Suite 330, Boston, 39MA 02111-1307, USA. 40 41@menu 42* Introduction:: 43 44* Tutorials:: 45 46* Development:: 47 48* Datatype Index:: 49 50* Function Index:: 51@end menu 52@end ifinfo 53 54@node Introduction, Tutorials, ,Top 55@chapter Introduction 56 57iksemel is an XML (eXtensible Markup Language) parser library 58designed for Jabber applications. It is coded in ANSI C for POSIX 59compatible environments, thus highly portable. It is free software 60released under the GNU Lesser General Public License. 61 62The purprose of this manual is to tell you how to use the facilities 63of the iksemel library. Manual is written with the assumption that you 64are familiar with the C programming language, basic programming 65concepts, XML and Jabber protocol. 66 67@section Compiling the Library 68 69You need to install MinGW (@url{http://mingw.org}) under Windows to be able 70to compile iksemel. Although not tested by the author, Cygwin should 71work equally well. 72 73Library can be built with: 74 75@example 76./configure 77make 78@end example 79 80If you want to make a self test: 81 82@example 83make test 84@end example 85 86Now you can install it with: 87 88@example 89make install 90@end example 91 92 93@section Using iksemel in Applications 94 95You need to include @file{iksemel.h} file in your source to access library API. 96You can do this with: 97 98@code{#include "iksemel.h"} 99 100Now you can use iksemel functions and compile your source. In able to link 101your compiled object files and generate your executable program, you have to 102link with iksemel library. This can be done with: 103 104@example 105gcc -o myprg src1.o src2.o src3.o -liksemel 106@end example 107 108iksemel registers itself with pkg-config while installing, so if you are using 109autotools in your program, you can simply check the availability of iksemel 110and configure your build process accordingly with: 111 112@example 113PKG_CHECK_MODULES(IKSEMEL,iksemel,,exit) 114@end example 115 116This would result in IKSEMEL_LIBS and IKSEMEL_CFLAGS substitution variables 117set to correct values. 118 119@node Tutorials,Development,Introduction,Top 120@chapter Tutorials 121 122@ifinfo 123@menu 124* Parsing an XML Document:: 125 126* Working with XML Trees:: 127 128* XML Streams:: 129 130* Writing a Jabber Client:: 131 132* Utility Functions:: 133@end menu 134@end ifinfo 135 136 137@comment ============================================================ 138@node Parsing an XML Document,Working with XML Trees,,Tutorials 139@section Parsing an XML Document 140 141iksemel parser sequentally processes the XML document. Each encountered XML 142element (i.e. tags, character data, comments, processing instructions, etc.) 143is reported to your application by calling the hook functions you have provided. 144This type of interface is called SAX (serial access) interface. 145 146@tindex iksparser 147Parser stores its state in a small structure. This structure is referenced by 148@code{iksparser} type, and managed with following functions: 149 150@deftypefun iksparser* iks_sax_new (void* @var{user_data}, iksTagHook* @var{tagHook}, iksCDataHook* @var{cdataHook}); 151This function allocates and initializes a parser structure. If allocation fails, 152NULL value is returned. @var{user_data} is passed directly to hook functions. 153@end deftypefun 154 155@deftp Typedef iksTagHook 156int iksTagHook (void* @var{user_data}, char* @var{name}, char** @var{atts}, int @var{type}); 157 158This function is called when a tag parsed. @var{name} is the name of the tag. If tag has 159no attributes @var{atts} is NULL, otherwise it contains a null terminated list of 160pointers to tag's attributes and their values. If return value isn't @code{IKS_OK}, 161it is passed immediately to the caller of the @code{iks_parse}. 162 163@var{type} is one of the following: 164@table @code 165@item IKS_OPEN 166Opening tag, i.e. <tag attr='value'> 167@item IKS_CLOSE 168Closing tag, i.e. </tag> 169@item IKS_SINGLE 170Standalone tag, i.e. <tag attr='value'/> 171@end table 172@end deftp 173 174@deftp Typedef iksCDataHook 175int iksCDataHook (void* @var{user_data}, char* @var{data}, size_t @var{len}); 176 177@var{data} is a pointer to the character data. Encoding is UTF-8 and it isn't terminated 178with a null character. Size of the data is given with @var{len} in bytes. This function 179can be called several times with smaller sized data for a single string. If 180return value isn't @code{IKS_OK}, it is passed immediately to the caller of the 181@code{iks_parse}. 182@end deftp 183 184@deftypefun int iks_parse (iksparser* @var{prs}, char *@var{data}, size_t @var{len}, int @var{finish}); 185You give XML document to the parser with this function. @var{data} 186is a @var{len} bytes string. If @var{len} is zero, data must be a null 187terminated string. 188 189If @var{finish} value is zero, parser waits for more data later. If you 190want to finish parsing without giving data, call it like: 191@example 192iks_parse (my_parser, NULL, 0, 1); 193@end example 194 195You should check the return value for following conditions: 196@table @code 197@item IKS_OK 198There isn't any problem. 199@item IKS_NOMEM 200Not enough memory. 201@item IKS_BADXML 202Document is not well-formed. 203@item IKS_HOOK 204Your hook decided that there is an error. 205@end table 206@end deftypefun 207 208@deftypefun void iks_parser_delete (iksparser* @var{prs}); 209This function frees parser structure and associated data. 210@end deftypefun 211 212Now we have learned how to create and use a sax parser. Lets parse a simple 213XML document. Write following code into a @file{test.c} file. 214 215@smallexample 216#include <stdio.h> 217#include <iksemel.h> 218 219int pr_tag (void *udata, char *name, char **atts, int type) 220@{ 221 switch (type) @{ 222 case IKS_OPEN: 223 printf ("TAG <%s>\n", name); 224 break; 225 case IKS_CLOSE: 226 printf ("TAG </%s>\n", name); 227 break; 228 case IKS_SINGLE: 229 printf ("TAG <%s/>\n", name); 230 break; 231 @} 232 if (atts) @{ 233 int i = 0; 234 while (atts[i]) @{ 235 printf (" ATTRIB %s='%s'\n", atts[i], atts[i+1]); 236 i += 2; 237 @} 238 @} 239 return IKS_OK; 240@} 241 242enum ikserror pr_cdata (void *udata, char *data, size_t len) 243@{ 244 int i; 245 printf ("CDATA ["); 246 for (i = 0; i < len; i++) 247 putchar (data[i]); 248 printf ("]\n"); 249 return IKS_OK; 250@} 251 252int main (int argc, char *argv[]) 253@{ 254 iksparser *p; 255 p = iks_sax_new (NULL, pr_tag, pr_cdata); 256 switch (iks_parse (p, argv[1], 0, 1)) @{ 257 case IKS_OK: 258 puts ("OK"); 259 break; 260 case IKS_NOMEM: 261 puts ("Not enough memory"); 262 exit (1); 263 case IKS_BADXML: 264 puts ("XML document is not well-formed"); 265 exit (2); 266 case IKS_HOOK: 267 puts ("Our hooks didn't like something"); 268 exit (2); 269 @} 270 iks_parser_delete (p); 271 return 0; 272@} 273@end smallexample 274 275Now compile and test it with: 276 277@example 278gcc -o test test.c -liksemel 279./test "<test>Hello<br/>World!</test>" 280./test "<lala a='12' b='42'/>" 281@end example 282 283@heading Error Handling 284 285XML standart states that once an error is detected, the processor must not continue 286normal processing (i.e. it must not pass character data or markup information to 287the application). So iksemel stops processing immediately when it encounters a 288syntax error, or one of your hook functions return any one value than @code{IKS_OK}, 289and @code{iks_parse} function returns with the error code. 290 291Since it is useful for debugging, iksemel provides functions to get position of 292the error. Position is usually at the starting character for syntax errors. Since 293your hooks are called after whole element (i.e. markup or character data) is 294passed, position is at the end of the erroneous element for @code{IKS_HOOK} errors. 295 296@deftypefun {unsigned long} iks_nr_bytes (iksparser* @var{prs}); 297Returns how many number of bytes parsed. 298@end deftypefun 299 300@deftypefun {unsigned long} iks_nr_lines (iksparser* @var{prs}); 301Returns how many number of lines parsed. 302@end deftypefun 303 304If you want to parse another document with your parser again, you should use 305the following function to reset your parser. 306 307@deftypefun void iks_parser_reset (iksparser* @var{prs}); 308Resets the parser's internal state. 309@end deftypefun 310 311 312@comment ============================================================ 313@node Working with XML Trees,XML Streams,Parsing an XML Document,Tutorials 314@section Working with XML Trees 315 316SAX interface uses very little memory, but it forces you to access XML 317documents sequentally. In many cases you want to keep a tree like 318representation of XML document in memory and want to access and 319modify its content randomly. 320 321iksemel provides functions for efficiently creating such trees either 322from documents or programmaticaly. You can access and modify this 323tree and can easily generate a new XML document from the tree. 324 325This is called DOM (Document Object Model) interface. 326 327@ifinfo 328@menu 329* Memory Management:: 330 331* Creating a Tree:: 332 333* Accessing the Tree:: 334 335* Converting a Tree into an XML Document:: 336 337* Parsing an XML Document into a Tree:: 338@end menu 339@end ifinfo 340 341 342@comment ============================================================ 343@node Memory Management,Creating a Tree,,Working with XML Trees 344@subsection Memory Management 345 346Since keeping whole document content uses a lot of memory and requires 347many calls to OS's memory allocation layer, iksemel uses a simple object 348stack system for minimizing calls to the @code{malloc} function and releasing 349all the memory associated with a tree in a single step. 350 351A parsed XML tree contains following objects: 352@table @samp 353@item Nodes 354These are basic blocks of document. They can contain a tag, attribute pair 355of a tag, or character data. Tag nodes can also contain other nodes as 356children. Node structure has a small fixed size depending on the node type. 357@item Names 358Names of tags and attributes. They are utf-8 encoded small strings. 359@item Character Data 360They are similar to names but usually much bigger. 361@end table 362 363iksemel's object stack has two separate areas for keeping these data objects. 364Meta chunk contains all the structures and aligned data, while the data chunk 365contains strings. Each chunk starts with a choosen size memory block, then 366when necessary more blocks allocated for providing space. Unless there is a big 367request, each block is double the size of the previous block, thus real memory 368needs are quickly reached without allocating too many blocks, or wasting 369memory with too big blocks. 370 371@deftp Typedef ikstack 372This is a structure defining the object stack. Its fields are private 373and subject to change with new iksemel releases. 374@end deftp 375 376@deftypefun {ikstack *} iks_stack_new (size_t @var{meta_chunk}, size_t @var{data_chunk}); 377Creates an object stack. @var{meta_chunk} is the initial size of the 378data block used for structures and aligned data. @var{data_chunk} is 379the initial size of the data block used for strings. They are both in byte units. 380 381These two initial chunks and a small object stack structure is allocated in 382one @code{malloc} call for optimization purproses. 383@end deftypefun 384 385@deftypefun {void *} iks_stack_alloc (ikstack * @var{stack}, size_t @var{size}); 386Allocates @var{size} bytes of space from the object stack's meta chunk. 387Allocated space is aligned on platform's default alignment boundary and 388isn't initialized. Returns a pointer to the space, or NULL if there isn't enough 389space available and allocating a new block fails. 390@end deftypefun 391 392@deftypefun {void *} iks_stack_strdup (ikstack * @var{stack}, const char * @var{src}, size_t @var{len}); 393Copies given string @var{src} into the object stack's data chunk. Returns a 394pointer to the new string, or NULL if there isn't enough space in the stack. 395If @var{len} is zero string must be null terminated. 396@end deftypefun 397 398@deftypefun void iks_stack_delete (ikstack * @var{stack}); 399Gives all memory associated with object stack to the system. 400@end deftypefun 401 402Since character data sections are usually parsed in separate blocks, 403a growable string implementation is necessary for saving memory. 404 405@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}); 406This function appends the string @var{src} to the string @var{old} in the 407stack's data chunk. If @var{old} is NULL it behaves like @code{iks_stack_strdup}. 408Otherwise @var{old} has to be a string created with @code{iks_stack_strdup} 409or @code{iks_stack_strcat} functions. 410 411If @var{old_len} or @var{src_len} is zero, corresponding string must be null 412terminated. 413 414Since string can be moved into another block of the data chunk, you must use the 415returned value for new string, and must not reference to @var{old} anymore. 416Return value can be NULL if there isn't enough space in stack, and allocating a 417new block fails. 418@end deftypefun 419 420 421@comment ============================================================ 422@node Creating a Tree,Accessing the Tree,Memory Management,Working with XML Trees 423@subsection Creating a Tree 424 425@deftp Typedef iks 426This is a structure defining a XML node. Its fields are private and only 427accessed by following functions. 428@end deftp 429 430@deftypefun iks* iks_new (const char *@var{name}); 431Creates an object stack and creates a IKS_TAG type of node with given 432tag name inside the stack. Tag name is also copied into the stack. 433Returns the node pointer, or NULL if there isn't enough memory. 434@end deftypefun 435 436@deftypefun iks* iks_new_within (const char *@var{name}, ikstack* @var{stack}); 437Creates a IKS_TAG type of node with the given tag name. Node and tag 438name is allocated inside the given object stack. Returns the node 439pointer, or NULL if there isn't enough memory. 440@end deftypefun 441 442@deftypefun iks* iks_insert (iks *@var{x}, const char *@var{name}); 443Creates a IKS_TAG type of node with the given tag name. Node and tag 444name is allocated inside the @var{x} node's object stack and linked 445to @var{x} as a child node. Returns the node pointer, or NULL if there 446isn't enough memory. 447@end deftypefun 448 449@deftypefun iks* iks_insert_cdata (iks* @var{x}, const char* @var{data}, size_t @var{len}); 450Creates a IKS_CDATA type of node with given character data. Node is 451allocated inside the @var{x} node's object stack and linked to @var{x} 452as a child node. Data is copied as well. If @var{len} is zero data must 453be a null terminated string. Returns the node pointer, or NULL if 454there isn't enough memory. 455@end deftypefun 456 457@deftypefun iks* iks_insert_attrib (iks* @var{x}, const char* @var{name}, const char* @var{value}); 458Creates a IKS_ATTRIBUTE type of node with given attribute name and the 459value. Node is allocated inside the @var{x} node's object stack and 460linked to @var{x} as an attribute node. Attribute name and value is 461copied as well. Returns the node pointer, or NULL if there isn't 462enough memory. 463 464Reinserting another value with same attribute name changes an attribute's 465value. If @var{value} is NULL, attribute is removed from the tag. 466@end deftypefun 467 468@deftypefun iks* iks_insert_node (iks* @var{x}, iks* @var{y}); 469Links node @var{y} to node @var{x} as a child node. Nodes are not copied 470between object stacks, be careful. 471@end deftypefun 472 473@deftypefun void iks_hide (iks *@var{x}); 474Changes the links of the other nodes so that @var{x} becomes invisible. 475It stays in the same object stack with neighbour nodes, be careful. 476@end deftypefun 477 478@deftypefun void iks_delete (iks *@var{x}); 479Frees the object stack of the node @var{x}. 480@end deftypefun 481 482Now lets create a tree representation of following XML document: 483 484@example 485<message type='chat' from='bob@@bd.com'> 486<subject>song lyric</subject><priority>high</priority> 487<body> 488<em style='underline'>here is the correct version:</em> 489i just don't see why i should even care 490it's not dark yet, but it's getting there 491</body> 492</message> 493@end example 494 495here is the code: 496 497@example 498iks *x, *y, *z; 499 500x = iks_new ("message"); 501iks_insert_attrib (x, "type", "chat"); 502iks_insert_attrib (x, "from", "bob@@bd.com"); 503iks_insert_cdata (x, "\n", 1); 504iks_insert_cdata (iks_insert (x, "subject"), "song lyric", 10); 505iks_insert_cdata (iks_insert (x, "priority"), "high", 4); 506iks_insert_cdata (x, "\n", 1); 507y = iks_insert (x, "body"); 508iks_insert_cdata (y, "\n", 1); 509z = iks_insert (y, "em"); 510iks_insert_attrib (z, "style", "underline"); 511iks_insert_cdata (z, "here is the correct version", 0); 512iks_insert_cdata (y, "\n", 1); 513iks_insert_cdata (y, "i just don't see why", 0); 514iks_insert_cdata (y, "i should even care\n", 0); 515iks_insert_cdata (y, "it's not dark yet,", 0); 516iks_insert_cdata (y, "but it's getting there\n", 0); 517iks_insert_cdata (x, "\n", 1); 518@end example 519 520Notice how newlines are inserted for proper formatting of document. They aren't 521necessary for representing data, but they make it easier to read document for 522humans. 523 524Also notice how @code{iks_insert} and @code{iks_insert_cdata} chained. 525 526There are also functions for duplicating xml trees. They are: 527 528@deftypefun {iks *} iks_copy (iks* @var{x}); 529Creates a full copy of the tree in a newly created object stack. 530@end deftypefun 531 532@deftypefun {iks *} iks_copy_within (iks* @var{x}, ikstack *@var{s}); 533Creates a full copy of the tree in given object stack. 534@end deftypefun 535 536@comment ============================================================ 537@node Accessing the Tree,Converting a Tree into an XML Document,Creating a Tree,Working with XML Trees 538@subsection Accessing a Tree 539 540Basic access functions allow you to move on the tree: 541 542@deftypefun iks* iks_next (iks* @var{x}); 543@end deftypefun 544@deftypefun iks* iks_prev (iks* @var{x}); 545@end deftypefun 546@deftypefun iks* iks_parent (iks* @var{x}); 547@end deftypefun 548@deftypefun iks* iks_child (iks* @var{x}); 549@end deftypefun 550@deftypefun iks* iks_attrib (iks* @var{x}); 551@end deftypefun 552 553These functions return a pointer to the next, previous, parent, first child, 554and first attribute node of the given node @var{x}. If that node doesn't 555exist or @var{x} is NULL, a NULL value is returned. 556 557@deftypefun {iks *} iks_root (iks *@var{x}); 558Returns the topmost parent node of the @var{x}. 559@end deftypefun 560 561@deftypefun iks* iks_next_tag (iks* @var{x}); 562@end deftypefun 563@deftypefun iks* iks_prev_tag (iks* @var{x}); 564@end deftypefun 565@deftypefun iks* iks_first_tag (iks* @var{x}); 566@end deftypefun 567 568These functions return a pointer to the next, previous, first child node 569of the given node @var{x}. Only tag nodes are considered, other type 570of the nodes are skipped. If such a node doesn't exist or @var{x} is NULL, 571a NULL value is returned. 572 573Another group of functions allow you to access specific information and 574content of the nodes: 575 576@deftypefun ikstack* iks_stack (iks* @var{x}); 577Returns the object stack which node @var{x} stays. 578@end deftypefun 579 580@deftypefun {enum ikstype} iks_type (iks* @var{x}); 581Returns the type of the node. 582 583@tindex ikstype 584@table @code 585@item IKS_TAG 586Node is a tag and can contain child nodes and attributes. 587@item IKS_CDATA 588Node contains character data. 589@item IKS_ATTRIBUTE 590Node contains an attribute and its value. 591@end table 592@end deftypefun 593 594@deftypefun char* iks_name (iks* @var{x}); 595Returns the name of the tag for nodes with the type @var{IKS_TAG}. 596Returns an attribute's name for nodes of type IKS_ATTRIBUTE. 597@end deftypefun 598 599@deftypefun char* iks_cdata (iks* @var{x}); 600Returns a pointer to node's character data if available, NULL otherwise. 601Returns an attribute's value for nodes of type IKS_ATTRIBUTE. 602@end deftypefun 603 604@deftypefun size_t iks_cdata_size (iks *@var{x}); 605Returns the size of the node's character data in bytes. 606@end deftypefun 607 608@deftypefun int iks_has_children (iks *@var{x}); 609Returns a non-zero value if node @var{x} has a child node. 610@end deftypefun 611 612@deftypefun int iks_has_attribs (iks *@var{x}); 613Returns a non-zero value if node @var{x} has attributes. 614@end deftypefun 615 616Last group of the functions simplifies finding and accessing the content 617of a specific node: 618 619@deftypefun iks* iks_find (iks *@var{x}, const char *@var{name}); 620Searches a IKS_TAG type of node with @var{name} as tag name in child 621nodes of @var{x}. Returns a pointer to the node if found, NULL otherwise. 622@end deftypefun 623 624@deftypefun char* iks_find_cdata (iks* @var{x}, const char* @var{name}); 625Searches a IKS_TAG type of node with @var{name} as tag name in child 626nodes of @var{x}. Returns a pointer to the character data of the node's 627first child node if found, NULL otherwise. 628@end deftypefun 629 630@deftypefun char* iks_find_attrib (iks* @var{x}, const char* @var{name}); 631Searches an attribute with given name in attributes of the @var{x}. 632Returns a pointer to attribute value if found, NULL otherwise. 633@end deftypefun 634 635@deftypefun {iks *} iks_find_with_attrib (iks *@var{x}, const char *@var{tagname}, const char *@var{attrname}, const char *@var{value}); 636Searches for a child tag of @var{x} which has an attribute with name 637@var{attrname} and value @var{value}. If @var{tagname} isn't NULL, 638name of the tag must also match. Returns a pointer to the node if found, 639NULL otherwise. 640@end deftypefun 641 642Here is an example which demonstrates accessing file names in a fictitious 643XML playlist file: 644 645@example 646<playlist> 647 <item type='mpg'> 648 <name>/home/madcat/download/matrix_rev_trailer.mpg</name> 649 <duration>1:17</duration> 650 </item> 651 <item type='rm'> 652 <name>/home/madcat/anim/clementine_ep1.rm</name> 653 <duration>22:00</duration> 654 </item> 655 <item type='avi'> 656 <name>/home/madcat/anim/futurama/ep101.avi</name> 657 <subtitle>/home/madcat/subs/futurama/ep101.txt</subtitle> 658 <duration>30:00</duration> 659 </item> 660 <repeat/> 661 <fullscreen/> 662 <noui/> 663</playlist> 664@end example 665 666and here is the code: 667 668@example 669#include <stdio.h> 670#include <iksemel.h> 671 672int main (int argc, char *argv[]) 673@{ 674 iks *x, *y; 675 int e; 676 677 if (argc < 2) @{ 678 printf ("usage: %s <playlistfile>", argv[0]); 679 return 0; 680 @} 681 e = iks_load (argv[1], &x); 682 if (e != IKS_OK) @{ 683 printf ("parse error %d\n", e); 684 return 1; 685 @} 686 if (iks_find (x, "repeat")) puts ("repeat mode enabled"); 687 y = iks_child (x); 688 while (y) @{ 689 if (iks_type (y) == IKS_TAG 690 && strcmp (iks_name (y), "item") == 0) @{ 691 printf ("Filename: [%s]\n", iks_find_cdata (y, "name")); 692 @} 693 y = iks_next (y); 694 @} 695 iks_delete (x); 696 return 0; 697@} 698@end example 699 700 701@comment ============================================================ 702@node Converting a Tree into an XML Document,Parsing an XML Document into a Tree,Accessing the Tree,Working with XML Trees 703@subsection Converting a Tree to an XML Document 704 705There is a function for converting given XML tree into a null terminated string. 706 707@deftypefun {char *} iks_string (ikstack* @var{stack}, iks* @var{x}); 708Converts given tree into a string. String is created inside the given object 709stack. Returns a pointer to the string, or NULL if there isn't enough memory 710available. 711 712If @var{stack} is NULL, string is created inside an @code{iks_malloc}ed buffer. 713You can free it later with @code{iks_free} function. 714@end deftypefun 715 716Here is an example which builds a tree and print it. 717 718@example 719iks *x; 720char *t; 721 722x = iks_new ("test"); 723iks_insert_cdata (iks_insert (x, "a"), "1234", 4); 724iks_insert (x, "br"); 725iks_insert_cdata (x, "1234", 4); 726t = iks_string (iks_stack (x), x); 727puts (t); 728iks_delete (x); 729@end example 730 731 732@comment ============================================================ 733@node Parsing an XML Document into a Tree,,Converting a Tree into an XML Document,Working with XML Trees 734@subsection Parsing a Document into a Tree 735 736If you want to automatically convert an XML document into a tree, you can use 737iksemel's DOM parser. It is created with following function: 738 739@deftypefun iksparser* iks_dom_new (iks **@var{iksptr}); 740Creates a DOM parser. A pointer to the created XML tree is put into the 741variable pointed by @var{iksptr}. Returns a pointer to the parser, or NULL 742is there isn't enough memory. 743@end deftypefun 744 745Usage is same as SAX parser. You feed the data with @code{iks_parse}, and if 746there isn't an error, you can access to your tree from variable @code{*iksptr}. 747 748Here is a simple example: 749 750@example 751iks *x; 752iksparser *p; 753 754p = iks_dom_new (&x); 755if (IKS_OK != iks_parse (p, "<a>bcd</a>", 9, 1)) @{ 756 puts ("parse error"); 757@} 758/* x is useable after that point */ 759 760/* this will print 'bcd' */ 761printf ("%s\n", iks_cdata (iks_child (x))); 762@end example 763 764If you know the size of the file ahead, or you have an approximate idea, 765you can tell this to the dom parser for choosing a better memory allocation 766strategy. Here is the function for this. 767 768@deftypefun void iks_set_size_hint (iksparser *@var{prs}, size_t @var{approx_size}); 769Parser @var{prs} must be a dom type parser. @var{approx_size} is the 770expected size of the xml document. Parser chooses its chunk size 771based on this information. Helps performance while processing big files. 772@end deftypefun 773 774If you already have your XML document in memory, you can simply parse 775it with: 776 777@deftypefun {iks *} iks_tree (const char *@var{xml_str}, size_t @var{len}, int *@var{err}); 778This function parses the buffer pointed by @var{xml_str}. If @var{len} is zero 779buffer is considered as a null terminated utf8 string. Returns the parsed tree, 780or NULL if there is an error. If @var{err} is not NULL, actual error code (returned 781by iks_parse) is put there. 782@end deftypefun 783 784Most of the times you want to load your configuration (or similar) files directly 785into trees. iksemel provides two functions to greatly simplify this: 786 787@deftypefun int iks_load (const char *@var{fname}, iks **@var{xptr}); 788Loads the XML file. Tree is placed into the variable pointed by @var{xptr}. 789@end deftypefun 790 791@deftypefun int iks_save (const char *@var{fname}, iks *@var{x}); 792Converts tree @var{x} into a string and saves to the file. 793@end deftypefun 794 795Both functions return same error codes as @code{iks_parse}. Some additional 796error codes are defined for indicating file problems. They are: 797 798@table @code 799@item IKS_FILE_NOFILE 800A file with the given name doesn't exist. 801@item IKS_FILE_NOACCESS 802Cannot open file. Possibly a permission problem. 803@item IKS_FILE_RWERR 804Read or write operation failed. 805@end table 806 807Here is a simple example which parses a file and saves it into another: 808 809@example 810iks *x; 811 812if (IKS_OK != iks_load ("file1.xml", &x)) @{ 813 puts ("loading error"); 814@} 815if (IKS_OK != iks_save ("file2.xml", x)) @{ 816 puts ("saving error"); 817@} 818@end example 819 820 821@comment ============================================================ 822@node XML Streams,Writing a Jabber Client,Working with XML Trees,Tutorials 823@section XML Streams 824 825XML streams function as containers for any XML chunks sent asynchronously 826between network endpoints. They are used for asyncronously exchanging 827relatively small payload of structured information between entities. 828 829A stream is initiated by one of hosts connecting to the other, and sending a 830<stream:stream> tag. Receiving entity replies with a second XML stream 831back to the initiating entity within the same connection. Each unit of 832information is send as a direct child tag of the <stream:stream> tag. 833Stream is closed with </stream:stream>. 834 835XML streams use a subset of XML. Specifically they should not contain 836processing instructions, non-predefined entities, comments, or DTDs. 837 838Jabber protocol uses XML streams for exchanging messages, presence 839information, and other information like authorization, search, time and 840version queries, protocol extensions. 841 842iksemel provides you a stream parser, which automatically handles connection 843to the server, and calls your hook function with incoming information 844parsed and converted to an XML tree. 845 846You can create such a parser with: 847 848@deftypefun iksparser* iks_stream_new (char* @var{name_space}, void* @var{user_data}, iksStreamHook* @var{streamHook}); 849Allocates and initalizes a stream parser. @var{name_space} indicates the 850stream type, jabber clients use "jabber:client" namespace. @var{user_data} 851is passed directly to your hook function. 852@end deftypefun 853 854@deftp Typedef iksStreamHook 855int iksStreamHook (void* @var{user_data}, int @var{type}, iks* @var{node}); 856 857Depending on the value of the @var{type}, @var{node} contains: 858@table @code 859@item IKS_NODE_START 860Got the <stream:stream> tag, namespace, stream id and other information 861is contained in the @var{node}. 862@item IKS_NODE_NORMAL 863A first level child of the <stream:stream> tag is received. @var{node} contains 864the parsed tag. If you are connected to a jabber server, you can get <message>, 865<presence>, or <iq> tags. 866@item IKS_NODE_ERROR 867Got a <stream:error> tag, details can be accessed from @var{node}. 868@item IKS_NODE_STOP 869</stream:stream> tag is received or connection is closed, @var{node} is @code{NULL}. 870@end table 871 872Freeing the node with @code{iks_delete} is up to you. 873@end deftp 874 875You can manually feed this parser with @code{iks_parse} function, but using 876iksemel's connection facilities is easier for most of the cases. 877 878This functions return @code{IKS_OK} for success. Error codes of @code{iks_parse} 879are used in same manner. Following additional codes are defined for 880network related problems: 881 882@table @code 883@item IKS_NET_NODNS 884Hostname lookup failed. Possible reasons: hostname is incorrect, 885you are not online, your dns server isn't accessible. 886@item IKS_NET_NOSOCK 887Socket cannot created. 888@item IKS_NET_NOCONN 889Connection attemp failed. Possible reasons: host is not an XML stream 890server, port number is wrong, server is busy or closed for the moment. 891@item IKS_NET_RWERR 892@code{send} or @code{recv} call is failed when attempting to exchange 893the data with the server. You should close the connection with @code{iks_disconnect} 894after getting this error from data transfer functions. 895@end table 896 897@deftypefun int iks_connect_tcp (iksparser *@var{prs}, const char *@var{server}, int @var{port}); 898This function connects the parser to a server and sends stream header for you. 899@var{server} is the host name of the server and @var{port} is the tcp port 900number which server is listening to. You can use @code{IKS_JABBER_PORT} 901macro for the default jabber client port (5222). 902@end deftypefun 903 904@deftypefun int iks_connect_fd (iksparser *@var{prs}, int @var{fd}); 905Attaches parser to an already opened connection. @var{fd} is the socket 906descriptor. Note that @code{iks_disconnect} doesn't close the socket 907for this kind of connection, opening and closing of the socket is up to your 908application. Stream header is not sent automatically. You can use 909@code{iks_send_header} function for sending it. 910@end deftypefun 911 912@deftypefun void iks_disconnect (iksparser *@var{prs}); 913Closes connection to the server, and frees connection resources. 914@end deftypefun 915 916After successfully connecting to a server, you can use following functions 917for exchanging information with server. 918 919@deftypefun int iks_recv (iksparser* @var{prs}, int @var{timeout}); 920If @var{timeout} is @code{-1}, waits until some data arrives from server, 921and process the data. Your stream hook can be called if a complete 922chunk is arrived. 923 924If @var{timeout} is a positive integer, @code{iks_recv} returns if no data 925arrives for @var{timeout} seconds. 926 927If @var{timeout} is zero, @code{iks_recv} checks if there is any data 928waiting at the network buffer, and returns without waiting for data. 929@end deftypefun 930 931@deftypefun int iks_fd (iksparser* @var{prs}); 932Returns the file descriptor of the connected socket. You can use this in 933your @code{select} function or some other input loop to act whenever 934some data from the server arrives. This value of only valid between 935a successful @code{iks_connect_tcp} and @code{iks_disconnect}. 936@end deftypefun 937 938@deftypefun int iks_send (iksparser* @var{prs}, iks* @var{x}); 939Converts the tree given in @var{x} to a string, and sends to the server. 940String is created inside the object stack of @var{x}. 941@end deftypefun 942 943@deftypefun int iks_send_raw (iksparser* @var{prs}, char* @var{xmlstr}); 944Sends the string given in @var{xmlstr} to the server. 945@end deftypefun 946 947@deftypefun int iks_send_header (iksparser *@var{prs}, char *@var{to}); 948Sends the stream header. @var{to} is the name of the server. 949Normally @code{iks_connect_tcp} function calls this for you. This 950is only useful if you are using @code{iks_connect_fd}. 951@end deftypefun 952 953Sometimes it is useful to log incoming and outgoing data to your parser 954for debugging your applications. iksemel provides a logging facility for you. 955 956@deftypefun void iks_set_log_hook (iksparser* @var{prs}, iksLogHook* @var{logHook}); 957Sets the log function for your stream parser. You can't use this function 958on any other type of parser. 959@end deftypefun 960 961@deftp Typedef iksLogHook 962void iksLogHook (void* @var{user_data}, const char* @var{data}, size_t @var{size}, int @var{is_incoming}); 963 964@var{user_data} is same value which you give with @code{iks_stream_new}. 965@var{data} is @var{size} bytes of data. Be very careful that this data may be 966coming from other side of the connection and can contain malicius bytes. It isn't 967checked by iksemel yet, so you should check it yourself before displaying or 968passing to other systems in your application or computer. If @var{is_incoming} 969is a non-zero value, data is incoming from server, otherwise it is outgoing to the 970server. 971@end deftp 972 973 974@comment ============================================================ 975@node Writing a Jabber Client,Utility Functions,XML Streams,Tutorials 976@section Writing a Jabber Client 977 978@ifinfo 979@menu 980* Security:: 981 982* Packets:: 983 984* Packet Filter:: 985 986* Creating Common Packets:: 987 988@end menu 989@end ifinfo 990 991@comment ============================================================ 992@node Security,Packets,,Writing a Jabber Client 993@subsection Security 994 995iksemel supports TLS protocol for encrypted communication and SASL 996protocol for authentication. TLS is handled by gnutls library. 997 998@deftypefun int iks_has_tls (void); 999If iksemel is compiled with gnutls library, this function returns a non-zero 1000value indicating you can try encrypted connection with the server. 1001@end deftypefun 1002 1003@deftypefun int iks_start_tls (iksparser* @var{prs}); 1004Starts a TLS handshake over already connected parser. Returns IKS_OK or 1005one of the IKS_NET_ errors. If handshake succeeds you'll get another 1006stream header from server. 1007@end deftypefun 1008 1009@deftypefun int iks_is_secure (iksparser* @var{prs}); 1010Returns a non-zero value if a secure connection is fully established 1011between server. 1012@end deftypefun 1013 1014@deftypefun int iks_start_sasl (iksparser* @var{prs}, enum ikssasltype @var{type}, char* @var{username}, char* @var{pass}); 1015Starts SASL operation. 1016@end deftypefun 1017 1018See tools/iksroster.c for a good example. 1019 1020@comment ============================================================ 1021@node Packets,Packet Filter,Security,Writing a Jabber Client 1022@subsection Packets 1023 1024iksemel can parse a jabber XML node and provide you a public packet 1025structure which contains information like node type and subtype, id, 1026namespace, sender's jabber id, etc. 1027 1028This handles a lot of node parsing for you. Packets are also used in 1029the packet filter subsystem. 1030 1031@deftypefun {ikspak *} iks_packet (iks *@var{x}); 1032Takes a node from stream and extracts information from it to a packet structure. 1033Structure is allocated inside the node's object stack. 1034@end deftypefun 1035 1036@tindex ikspak 1037@code{ikspak} structure has following fields: 1038 1039@table @code 1040@item iks *x; 1041This is a pointer to the node. 1042@item iksid *from; 1043Sender's jabber id in parsed form. See below for @code{iksid} structure. 1044@item iks *query; 1045A pointer to the <query> tag for IQ nodes. 1046@item char *ns; 1047Namespace of the content for IQ nodes. 1048@item char *id; 1049ID of the node. 1050@item enum ikspaktype type; 1051Type of the node. Possible types are: 1052 1053@table @code 1054@item IKS_PAK_NONE 1055Unknown node. 1056@item IKS_PAK_MESSAGE 1057Message node. 1058@item IKS_PAK_PRESENCE 1059Presence node with presence publishing operation. 1060@item IKS_PAK_S10N 1061Presence node with subscription operation. 1062@item IKS_PAK_IQ 1063IQ node. 1064@end table 1065@item enum iksubtype subtype; 1066Sub type of the node. Sub types for message nodes: 1067 1068@table @code 1069@item IKS_TYPE_NONE 1070A normal message. 1071@item IKS_TYPE_CHAT 1072Private chat message. 1073@item IKS_TYPE_GROUPCHAT 1074Multi user chat message. 1075@item IKS_TYPE_HEADLINE 1076Message from a news source. 1077@item IKS_TYPE_ERROR 1078Message error. 1079@end table 1080 1081Sub types for IQ nodes: 1082 1083@table @code 1084@item IKS_TYPE_GET 1085Asks for some information. 1086@item IKS_TYPE_SET 1087Request for changing information. 1088@item IKS_TYPE_RESULT 1089Reply to get and set requests. 1090@item IKS_TYPE_ERROR 1091IQ error. 1092@end table 1093 1094Sub types for subscription nodes: 1095 1096@table @code 1097@item IKS_TYPE_SUBSCRIBE, 1098Asks for subscribing to the presence. 1099@item IKS_TYPE_SUBSCRIBED, 1100Grants subscription. 1101@item IKS_TYPE_UNSUBSCRIBE, 1102Asks for unsubscribing to the presence. 1103@item IKS_TYPE_UNSUBSCRIBED, 1104Cancels subscription. 1105@item IKS_TYPE_ERROR 1106Presence error. 1107@end table 1108 1109Sub types for presence nodes: 1110 1111@table @code 1112@item IKS_TYPE_PROBE, 1113Asks presence status. 1114@item IKS_TYPE_AVAILABLE, 1115Publishes entity as available. More information can be found in @code{show} field. 1116@item IKS_TYPE_UNAVAILABLE 1117Publishes entity as unavailable. More information can be found in @code{show} field. 1118@end table 1119@item enum ikshowtype show; 1120Presence state for the presence nodes. 1121 1122@table @code 1123@item IKS_SHOW_UNAVAILABLE 1124Entity is unavailable. 1125@item IKS_SHOW_AVAILABLE 1126Entity is available. 1127@item IKS_SHOW_CHAT 1128Entity is free for chat. 1129@item IKS_SHOW_AWAY 1130Entity is away for a short time. 1131@item IKS_SHOW_XA 1132Entity is away for a long time. 1133@item IKS_SHOW_DND 1134Entity doesn't want to be disturbed. 1135@end table 1136@end table 1137 1138iksemel has two functions to parse and compare jabber IDs. 1139 1140@deftypefun {iksid *} iks_id_new (ikstack *@var{s}, const char *@var{jid}); 1141Parses a jabber id into its parts. @code{iksid} structure is created inside 1142the @var{s} object stack. 1143@end deftypefun 1144 1145@tindex iksid 1146@code{iksid} structure has following fields: 1147 1148@table @code 1149@item char *user; 1150User name. 1151@item char *server; 1152Server name. 1153@item char *resource; 1154Resource. 1155@item char *partial; 1156User name and server name. 1157@item char *full; 1158User name, server name and resource. 1159@end table 1160 1161You can access this fields and read their values. Comparing two parsed jabber 1162ids can be done with: 1163 1164@deftypefun int iks_id_cmp (iksid *@var{a}, iksid *@var{b}, int @var{parts}); 1165Compares @var{parts} of @var{a} and @var{b}. Part values are: 1166 1167@table @code 1168@item IKS_ID_USER 1169@item IKS_ID_SERVER 1170@item IKS_ID_RESOURCE 1171@end table 1172 1173@sp 1 1174You can combine this values with @code{or} operator. Some common combinations 1175are predefined for you: 1176 1177@table @code 1178@item IKS_ID_PARTIAL 1179@code{IKS_ID_USER | IKS_ID_SERVER} 1180@item IKS_ID_FULL 1181@code{IKS_ID_USER | IKS_ID_SERVER | IKS_ID_RESOURCE} 1182@end table 1183 1184Return value is @code{0} for equality. If entities are not equal a combination of 1185part values showing different parts is returned. 1186@end deftypefun 1187 1188 1189@comment ============================================================ 1190@node Packet Filter,Creating Common Packets,Packets,Writing a Jabber Client 1191@subsection Packet Filter 1192 1193Packet filter handles routing incoming packets to related functions. 1194 1195@tindex iksfilter 1196@deftypefun {iksfilter *} iks_filter_new (void); 1197Creates a new packet filter. 1198@end deftypefun 1199 1200@deftypefun void iks_filter_packet (iksfilter *@var{f}, ikspak *@var{pak}); 1201Feeds the filter with given packet. Packet is compared to registered rules and 1202hook functions of the matching rules are called in most matched to least 1203matched order. 1204@end deftypefun 1205 1206@deftypefun void iks_filter_delete (iksfilter *@var{f}); 1207Frees filter and rules. 1208@end deftypefun 1209 1210Rules are created with following function: 1211 1212@tindex iksrule 1213@deftypefun {iksrule *} iks_filter_add_rule (iksfilter *@var{f}, iksFilterHook *@var{filterHook}, void *@var{user_data}, @dots{}); 1214Adds a rule to the filter @var{f}. @var{user_data} is passed directly to your 1215hook function @var{filterHook}. 1216 1217A rule consist of one or more type and value pairs. Possible types: 1218@table @code 1219@item IKS_RULE_ID 1220Compares @code{char *} value to packet ids. 1221@item IKS_RULE_FROM 1222Compares @code{char *} value to packet senders. 1223@item IKS_RULE_FROM_PARTIAL 1224Compares @code{char *} value to packet sender. Ignores resource part of jabber id. 1225@item IKS_RULE_NS 1226Compares @code{char *} value to namespace of iq packets. 1227@item IKS_RULE_TYPE 1228Compares @code{int} value to packet types. 1229@item IKS_RULE_SUBTYPE 1230Compares @code{int} value to packet sub types. 1231@item IKS_RULE_DONE 1232Terminates the rule pairs. 1233@end table 1234@end deftypefun 1235 1236Here is an example which creates a filter and adds three rules: 1237@example 1238iksfilter *f; 1239 1240f = iks_filter_new (); 1241iks_filter_add_rule (f, on_msg, NULL, 1242 IKS_RULE_TYPE, IKS_PAK_MESSAGE, 1243 IKS_RULE_DONE); 1244iks_filter_add_rule (f, on_auth_result, NULL, 1245 IKS_RULE_TYPE, IKS_PAK_IQ, 1246 IKS_RULE_SUBTYPE, IKS_TYPE_RESULT, 1247 IKS_RULE_ID, "auth", 1248 IKS_RULE_DONE); 1249iks_filter_add_rule (f, on_roster_push, NULL, 1250 IKS_RULE_TYPE, IKS_PAK_IQ, 1251 IKS_RULE_SUBTYPE, IKS_TYPE_SET, 1252 IKS_RULE_NS, "jabber:iq:roster", 1253 IKS_RULE_DONE); 1254@end example 1255 1256@deftp Typedef iksFilterHook 1257int iksFilterHook (void *user_data, ikspak *pak); 1258 1259Your hook is called with your @var{user_data} and matching packet @var{pak}. 1260You can return two different values from your hook: 1261@table @code 1262@item IKS_FILTER_PASS 1263Packet is forwarded to least matching rules. 1264@item IKS_FILTER_EAT 1265Filtering process for the packet ends. 1266@end table 1267@end deftp 1268 1269You can remove the rules with following functions: 1270 1271@deftypefun void iks_filter_remove_rule (iksfilter *@var{f}, iksrule *@var{rule}); 1272Removes the rule from filter. 1273@end deftypefun 1274 1275@deftypefun void iks_filter_remove_hook (iksfilter *@var{f}, iksFilterHook *@var{filterHook}); 1276Remove the rules using @var{filterHook} function from filter. 1277@end deftypefun 1278 1279 1280@comment ============================================================ 1281@node Creating Common Packets,,Packet Filter,Writing a Jabber Client 1282@subsection Creating Common Packets 1283 1284A usual jabber network traffic contains many similar XML constructs. iksemel 1285provides several utility functions for creating them. They all generate an XML 1286tree, so you can add or modify some parts of the tree, and send to server then. 1287 1288@deftypefun {iks *} iks_make_auth (iksid *@var{id}, const char *@var{pass}, const char *@var{sid}); 1289Creates an authorization packet. @var{id} is your parsed jabber id, and @var{pass} 1290is your password. 1291 1292If stream id @var{sid} isn't NULL, SHA1 authentication is used, otherwise password 1293is attached in plain text. You can learn stream id from @code{IKS_STREAM_START} 1294packet in your stream hook like this: 1295 1296@example 1297char *sid; 1298 1299if (type == IKS_STREAM_START) @{ 1300 sid = iks_find_attrib (node, "id"); 1301@} 1302@end example 1303@end deftypefun 1304 1305@deftypefun {iks *} iks_make_msg (enum iksubtype @var{type}, const char *@var{to}, const char *@var{body}); 1306Creates a message packet. @var{type} is the message type, @var{to} is jabber id 1307of the recipient, @var{body} is the message. 1308@end deftypefun 1309 1310@deftypefun {iks *} iks_make_s10n (enum iksubtype @var{type}, const char *@var{to}, const char *@var{msg}); 1311Creates a presence packet for subscription operations. @var{type} is operation, 1312@var{to} is jabber id of the recipient, @var{msg} is a small message for 1313introducing yourself, or explaning the reason of why you are subscribing or 1314unsubscribing. 1315@end deftypefun 1316 1317@deftypefun {iks *} iks_make_pres (enum ikshowtype @var{show}, const char *@var{status}); 1318Creates a presence packet for publishing your presence. @var{show} is your 1319presence state and @var{status} is a message explaining why you are not 1320available at the moment, or what you are doing now. 1321@end deftypefun 1322 1323@deftypefun {iks *} iks_make_iq (enum iksubtype @var{type}, const char *@var{xmlns}); 1324Creates an IQ packet. @var{type} is operation type and @var{xmlns} is the 1325namespace of the content. You usually have to add real content to the <query> 1326tag before sending this packet. 1327@end deftypefun 1328 1329 1330@comment ============================================================ 1331@node Utility Functions,,Writing a Jabber Client,Tutorials 1332@section Utility Functions 1333 1334@subsection Memory Utilities 1335 1336@deftypefun {void *} iks_malloc (size_t @var{size}); 1337@end deftypefun 1338@deftypefun void iks_free (void *@var{ptr}); 1339@end deftypefun 1340 1341These are wrappers around ANSI malloc and free functions used by the 1342iksemel library itself. You can free the output of iks_string (only if you 1343passed it a NULL stack) with iks_free for example. That is important 1344if you are using a malloc debugger in your application but not in iksemel 1345or vice versa. 1346 1347@comment ============================================================ 1348@subsection String Utilities 1349 1350@deftypefun {char *} iks_strdup (const char *@var{src}); 1351@end deftypefun 1352@deftypefun int iks_strcmp (const char *@var{a}, const char *@var{b}); 1353@end deftypefun 1354@deftypefun int iks_strcasecmp (const char *@var{a}, const char *@var{b}); 1355@end deftypefun 1356@deftypefun int iks_strncmp (const char *@var{a}, const char *@var{b}, size_t @var{n}); 1357@end deftypefun 1358@deftypefun int iks_strncasecmp (const char *@var{a}, const char *@var{b}, size_t @var{n}); 1359@end deftypefun 1360@deftypefun size_t iks_strlen (const char *@var{src}); 1361@end deftypefun 1362 1363These functions work exactly like their ANSI equivalents except that they allow 1364NULL values for string pointers. If @var{src} is NULL, iks_strdup and iks_strlen 1365returns zero. If @var{a} or @var{b} is NULL in string comparisation functions 1366they return -1. 1367 1368Their usefulness comes from the fact that they can chained with DOM traversing 1369functions like this: 1370 1371@smallexample 1372if (iks_strcmp (iks_find_attrib (x, "id"), "x1") == 0) count++; 1373@end smallexample 1374 1375That example works even x doesn't have an 'id' attribute and iks_find_attrib 1376returns NULL. So you don't need to use temporary variables in such 1377situations. 1378 1379@comment ============================================================ 1380@subsection SHA1 Hash 1381 1382Secure Hash Algorithm (SHA1) is used in the Jabber authentication 1383protocol for encoding your password when sending to the server. 1384This is normally handled by iks_make_auth() function, but if you 1385want to handle it manually, or if you need a good hash function 1386for other purproses you can use these functions. 1387 1388@deftypefun iksha* iks_sha_new (void); 1389Allocates a structure for keeping calculation values and the state. 1390@end deftypefun 1391 1392@deftypefun void iks_sha_reset (iksha *@var{sha}); 1393Resets the state of the calculation. 1394@end deftypefun 1395 1396@deftypefun void iks_sha_hash (iksha *@var{sha}, const unsigned char *@var{data}, int @var{len}, int @var{finish}); 1397Calculates the hash value of the given data. If @var{finish} is non 1398zero, applies the last step of the calculation. 1399@end deftypefun 1400 1401@deftypefun void iks_sha_print (iksha *@var{sha}, char *@var{hash}); 1402Prints the result of a finished calculation into the buffer pointed by @var{hash} 1403in hexadecimal string form. Buffer must be at least 40 bytes long. String 1404is not null terminated. 1405@end deftypefun 1406 1407@deftypefun void iks_sha (const char *@var{data}, char *@var{hash}); 1408Calculates the hash value of @var{data} and prints into @var{hash}. 1409This is a helper function for simple hash calculations. It calls 1410other functions for the actual work. 1411@end deftypefun 1412 1413 1414@comment ============================================================ 1415 1416 1417@node Development,Datatype Index,Tutorials,Top 1418@chapter Development 1419 1420This chapter contains information on plan, procedure and standarts of 1421iksemel development. 1422 1423@section Roadmap 1424 1425There are three main functions iksemel tries to provide to applications: 1426@itemize @bullet 1427@item 1428A generic XML parser with SAX and DOM interfaces. 1429@item 1430XML stream client and server functionality. 1431@item 1432Utilities for Jabber clients. 1433@end itemize 1434 1435Goal of the iksemel is providing these functions while supporting embedded 1436environments, keeping usage simple, and having a robust implementation. 1437 1438Some decisions are made to reach this goal: 1439 1440Code is written in ANSI C with a single dependency on C library. Instead of 1441using expat or libxml, a simple built-in parser is used. Similarly glib and 1442gnu only features of glibc (like object stacks) are avoided and built-in 1443memory and string utilities are used. This may seem like code duplication 1444but since they are optimized for iksemel and only a few kb in size, 1445it isn't a big disadvantage. 1446 1447Code is placed files in a modular fashion, and different modules don't depend 1448on others' internal details. This allows taking unneeded functionality out when 1449building for low resource situations. 1450 1451It is tried to give functions names which are consistent, clear and short. 1452 1453API is documented with texinfo for high quality printed output and info file 1454output for fast and simple access during application development. Instead 1455of using an autogenerated system or simply listing function descriptions, 1456a task oriented tutorial approach is used. 1457 1458@section Coding Style 1459 1460Here is a short list describing preferred coding style for iksemel. 1461Please keep in mind when sending patches. 1462 1463@itemize @bullet 1464@item 1465Indentation is done with tabs. Aligning is done with spaces. 1466@item 1467Placement of braces is K&R style. 1468@item 1469Function names are put at the start of line. 1470@item 1471Function names are lowercase. 1472@item 1473Words of the function names are separated with underscore character. 1474@item 1475Structure and variable names are lowercase. 1476@item 1477Macro and enumarations names are uppercase. 1478@item 1479Exported library API is contained in the single iksemel.h file. 1480@item 1481Exported function names start with iks_ 1482@item 1483Exported structure and type names start with iks 1484@item 1485Exported macro and enumaration names start with IKS_ 1486@end itemize 1487 1488Here is an example: 1489 1490@smallexample 1491int 1492iks_new_func (char *text) 1493@{ 1494 int i; 1495 1496 i = an_internal_func (text); 1497 if (IKS_SOME_VALUE == i) @{ 1498 iks_some_func (text); 1499 i++; 1500 @} 1501 return i; 1502@} 1503@end smallexample 1504 1505@section Resources 1506 1507@itemize @bullet 1508@item 1509RFC 2279, UTF-8 format @url{http://www.ietf.org/rfc/rfc2279.txt} 1510@item 1511W3C Recommendation, Extensible Markup Language 1.0 @url{http://www.w3.org/TR/REC-xml} 1512@item 1513Annotated XML Specification @url{http://www.xml.com/axml/testaxml.htm} 1514@item 1515Jabber Protocol Documents @url{http://www.jabber.org/protocol/} 1516@end itemize 1517 1518 1519@comment ============================================================ 1520 1521 1522@node Datatype Index,Function Index,Development,Top 1523@unnumbered Datatype Index 1524@printindex tp 1525 1526 1527@node Function Index,,Datatype Index,Top 1528@unnumbered Function Index 1529@printindex fn 1530 1531 1532@contents 1533@bye 1534