iksemel.texi

linux平台或者windwos平台通用xml 解析器

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