/** @page index Libxr

This is a documentation for @b libxr: multi-transport RPC client/server library.

@section toc Table of Contents
@li @ref intro
@li @ref howto
@li @ref xdl
@li @ref xdlc
@li @ref xr-value.h "XR Value API"
@li @ref xr-call.h "XR Call API"
@li @ref xr-client.h "XR Client API"
@li @ref xr-server.h "XR Server API"

*/

/** @page intro Libxr Overview

Libxr is a library that allows for rapid implementation of RPC clients and
servers in C.

@section features Features

  - Multiple RPC transports. (XML-RPC and JSON-RPC)
  - RPC interface description language (XDL)
  - Persistent connections over HTTP/1.1
  - Server "session" support for non-persistent connections
  - Multi-platform support (Linux, Windows, ...)
  - SSLv3/TLSv1 using OpenSSL
  - IPV6 as soon as OpenSSL 0.9.9 is released
  - VALA language support for client interfaces
  - Multiple interfaces per server

@section description Description

Libxr has two parts, library itself and RPC interface description language
compiler (XDL compiler). Thanks to the XDL compiler, you can create and
implement complex RPC interfaces in a very short time. Here is an obligatory
"Hello world!" example XDL file:

@code
  namespace X;
  servlet Test {
    boolean sayHello()
    <%
      printf("Hello World!");
      return TRUE;
    %>
  }
@endcode

Whenever you call XTest.sayHello() RPC method, "Hello World!" will be printed to
the server's standard output.

For more information see HOWTO tutorial, libxr API documentation or tests/
directory.

*/

/** @page howto HOWTO

This HOWTO shows how to implement XML-RPC server and client in C using libxr.
As an example we will implement simple remote management interface for Zblok.

Interface specification:

@li Client must authenticate against zblok users database.
@li Client should be allowed to read status information about zblok.
@li Client should be able to change his/her password. 

@section Server

Server interface is implemented using so called servlet. Servlet is an object on
the server that has constructor, destructor and implements interface methods.

When client connects to the server, server creates @ref xr_servlet and waits for
RPCs. On the first RPC, servlet is looked up in the list of registered servlets
by the resource passed in the HTTP header and constructor is called.

Server interface can be described using @ref xdl. You can put implementation
code of servlet directly into XDL file. Following XDL code describes interface
of our Zblok management server.

@code
namespace ZM; // Zblok Management

// interface error codes
error AUTH_FAILED = 1;
error NOT_AUTHORIZED = 2;

// structure describing zblok user state
struct User
{
  string  username;
  string  realname;
  int     mail_usage;
}

// structure describing zblok folder state
struct Folder
{
  string  name;
  string  type;
  int     size;
}

// system status, combines previous two structures
struct SystemStatus
{
  int            uptime;
  array<User>    users;
  array<Folder>  folders;
}

servlet Server
{
  boolean       auth                (string username, 
                                     string password);
  SystemStatus  getSystemStatus     ();
  boolean       changeUserPassword  (string newpassword);
}
@endcode

Now we will use @ref xdlc to compile this XDL file into C source code that
implements client and server interfaces and stubs for implementation of servlet
methods.

@verbatim
xdl-compiler -i zblok.xdl -o .
@endverbatim

This command should create following files in the current directory:

@verbatim
.
|-- ZMCommon.c
|-- ZMCommon.h
|-- ZMCommon.xrm.h
|-- ZMServer.c
|-- ZMServer.h
|-- ZMServer.stubs.c
|-- ZMServer.stubs.h
|-- ZMServer.xrc.c
|-- ZMServer.xrc.h
|-- ZMServer.xrm.h
|-- ZMServer.xrs.c
`-- ZMServer.xrs.h
@endverbatim

You can inspect these files to see how things are implemented, but it is not
necessary. The most interesting file is ZMServer.stubs.c which implements
servlet methods. 

Next step is implementation of servlet methods in the XDL file:

@include zblok/zblok.xdl

Now that we have implemented servlet methods, we must create server. Libxr
offers multiple ways to implement server. The simplest way is this:

@include zblok/server.c

That's it! Server is done, now we have to compile it:

@verbatim
gcc -o zm-server server.c ZMCommon.c ZMServer.c ZMServer.stubs.c \
  ZMServer.xrs.c `pkg-config --cflags --libs libxr` -lssl -lcrypto
@endverbatim

@section Client

Ok, now we have server and we want to connect to it so we need to implement
client. Following code will connect to the server, authenticates user and
changes his password:

@include zblok/client.c

You can compile client code using:

@verbatim
gcc -o zm-client client.c ZMCommon.c ZMServer.c ZMServer.xrc.c \
  `pkg-config --cflags --libs libxr` -lssl -lcrypto
@endverbatim

And that's it.

*/

/** @page xdl XDL Language

XDL language is used to describe XML-RPC servlet interfaces and data
types. You may use @ref xdlc to compile XDL file into C source files
that implement client and server interfaces.

*/

/** @page xdlc XDL Language Compiler

XDL Compiler outputs following files: (Lets suppose that we have Test
servlet and EEE namespace)

<pre>
  .
  |-- EEETest.h        -- Test interface types definitions
  |-- EEETest.c        -- Test interface types access methods
  |-- EEETest.xrc.c    -- implementation of client interface for Test servlet
  |-- EEETest.xrm.h    -- marchalizers/demarchalizers for Test servlet types
  |-- EEETest.xrs.h    -- server interface public method for servlet registration
  |-- EEETest.xrs.c    -- servlet interface implementation
  |-- EEETest.stubs.h  -- servlet stubs header
  |-- EEETest.stubs.c  -- servlet stubs implementation
  |-- EEECommon.h      -- common types declared outside of servlet
  |-- EEECommon.c      -- common types access methods (for freeing/allocation)
  `-- EEECommon.xrm.h  -- marchalizers/demarchalizers for common types
</pre>

*/