Introduction

LuaXMLRPC is a Lua library to manage XML-RPC clients and servers. It enables a Lua program to:

Encode and decode XML-RPC messages without having to deal with XML code
Transform Lua objects into XML-RPC data types and vice-versa

LuaXMLRPC provides a simple API and an abstraction layer over XML avoiding manipulation of string representation of data structures. It also offers ways to express everything when needed.

LuaXMLRPC is based on LuaExpat and on Lua 5.0.

Data types

XML-RPC elements are usually represented by the simplest correspondent Lua object. When the correspondance is not obvious, a Lua table is used with a field specifying the element.

From XML-RPC to Lua

When converting from XML-RPC element to a Lua object, a table with a field tag is used. The child elements are stored at numbered indexes and white space is ignored.

XML-RPC data type Lua object

double
int
i4 number

string string

boolean boolean

struct
arrray table

other elements
{ tag = "element name", [1] = <first child>, [2] = <second child>, [3] = ..., }

A convertion from a Lua object to an XML-RPC can be made automatically or explicitly. The automatic conversion rules are:

Lua object XML-RPC data type

number double

string string

boolean boolean

{ key = val }
<struct> <member> <name>key</name> <value>val</value> </member> </struct>
val is converted according to the same rules.

In case of a table that has numeric keys, the resulting struct will have numbers as keys (but they will be treated as strings).

Explicit conversions can be forced by the creation of typed values (see function createTypedValue).

Basic support

client_encode (method_name, params*) => method_call
Build a XML-RPC document containing a methodCall element. It receives a string with the method's name and an optional list of parameters. The result is a string containing the XML-RPC document.
client_decode (method_response) => ok, list_results
Disassemble the server response into a Lua object. It receives a string containing the XML-RPC document representing the methodResponse element. The result is a boolean indicating wether the call was successful or not and a Lua table containing the results of the call, equivalent to the params element.
server_decode (method_call) => method_name, list_params
Disassemble the client request into a method's name and a Lua object. It receives a string containing the XML-RPC document representing the methodCall element. The result is a string with the name of the method to be called and a Lua table with all the arguments to be passed to it.
server_encode (object) => method_response
Build a XML-RPC document containing a methodResponse element. It receives a Lua object (a number, a string, a table etc.) with the response of the call to be sent. The result is a string containing the XML-RPC document.
createTypedValue (value, type)

Client side

The client side library offers the following functions:

call (url, method, params*)
Execute the call to method at location url with the given params (if any). The result is a Lua object containing the response. It could be a <params> or a <fault> XML-RPC element.

Example

Below is a small sample code displaying the use of the library in a client application.

require "xmlrpc"
require "luasocket"
require "xrh"

local ok, res = xrh.call ("http://www.oreillynet.com/meerkat/xml-rpc/server.php", "system.listMethods")
print (ok)
for i, v in pairs(res) do print ('\t', i, v) end

Introduction

Data types

From XML-RPC to Lua

From Lua to XML-RPC

Basic support

Client side

Example

Related documentation

Contents

XML-RPC data type	Lua object
double int i4	number
string	string
boolean	boolean
struct arrray	table
other elements	{ tag = "element name", [1] = <first child>, [2] = <second child>, [3] = ..., }