libxr — developer's documentation

- Main Page
- Related Pages
- Data Structures
- Files

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:

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

# 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 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 XDL Language. You can put implementation code of servlet directly into XDL file. Following XDL code describes interface of our Zblok management server.

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);
}

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

    xdl-compiler -i zblok.xdl -o .

This command should create following files in the current directory:

    .
    |-- 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

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:

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

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

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

# 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:

You can compile client code using:

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

And that's it.

Documentation for libxr, Mon Jan 6 2014 07:31:25.