iksemel.texi

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

@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;