366 lines
11 KiB
HTML
Executable File
366 lines
11 KiB
HTML
Executable File
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>LuaXMLRPC: XML-RPC interface to the Lua programming language</title>
|
|
<link rel="stylesheet" href="http://www.keplerproject.org/doc.css" type="text/css"/>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
|
|
</head>
|
|
<body>
|
|
|
|
<div id="container">
|
|
|
|
<div id="product">
|
|
<div id="product_logo"><a href="http://www.keplerproject.org">
|
|
<img alt="LuaXMLRPC logo" src="luaxmlrpc.png"/>
|
|
</a></div>
|
|
<div id="product_name"><big><b>LuaXMLRPC</b></big></div>
|
|
<div id="product_description">XML-RPC interface to the Lua programming language</div>
|
|
</div> <!-- id="product" -->
|
|
|
|
<div id="main">
|
|
|
|
<div id="navigation">
|
|
<h1>LuaXMLRPC</h1>
|
|
<ul>
|
|
<li><a href="index.html">Home</a>
|
|
<ul>
|
|
<li><a href="index.html#overview">Overview</a></li>
|
|
<li><a href="index.html#status">Status</a></li>
|
|
<li><a href="index.html#download">Download</a></li>
|
|
<li><a href="index.html#history">History</a></li>
|
|
<li><a href="index.html#credits">Credits</a></li>
|
|
<li><a href="index.html#contact">Contact</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Manual</strong>
|
|
<ul>
|
|
<li><a href="manual.html#introduction">Introduction</a></li>
|
|
<li><a href="manual.html#installation">Installation</a></li>
|
|
<li><a href="manual.html#data_types">Data types</a></li>
|
|
<li><a href="manual.html#basic">Basic support</a></li>
|
|
<li><a href="manual.html#client">Client side</a></li>
|
|
<li><a href="manual.html#server">Server side</a></li>
|
|
<li><a href="manual.html#references">References</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="examples.html">Examples</a></li>
|
|
<li><a href="license.html">License</a></li>
|
|
</ul>
|
|
</div> <!-- id="navigation" -->
|
|
|
|
<div id="content">
|
|
|
|
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
|
|
<p>LuaXMLRPC is a <a href="http://www.lua.org">Lua</a> library to
|
|
build <a href="http://www.xmlrpc.com">XML-RPC</a> clients and
|
|
servers. It enables a Lua program to:</p>
|
|
|
|
<ul>
|
|
<li>Encode and decode XML-RPC messages without having to deal with
|
|
XML code</li>
|
|
|
|
<li>Transform Lua objects into XML-RPC data types and
|
|
vice-versa</li>
|
|
</ul>
|
|
|
|
<p>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.-->
|
|
</p>
|
|
|
|
<p>LuaXMLRPC is based on <a href=
|
|
"http://www.keplerproject.org/luaexpat">LuaExpat</a> and on <a
|
|
href="http://www.lua.org">Lua 5.0</a>.
|
|
The abstraction layer over HTTP depends on <a href=
|
|
"http://www.tecgraf.puc-rio.br/luasocket">LuaSocket 2.0</a>.
|
|
</p>
|
|
|
|
<h2><a name="installation"></a>Installation</h2>
|
|
|
|
<p>LuaXMLRPC is composed by three Lua files.
|
|
These files should be
|
|
copied to a directory named <code>xmlrpc</code> created in your
|
|
<code>LUA_PATH</code>.</p>
|
|
|
|
<p>
|
|
LuaXMLRPC follows the
|
|
<a href="http://www.keplerproject.org/compat">package model</a>
|
|
for Lua 5.1, therefore this package should be "installed".
|
|
In other words,
|
|
if you are using Lua 5.0, the files <tt>compat-5.1.c</tt> and
|
|
<tt>compat-5.1.h</tt> must be used in the compilation and the file
|
|
<tt>compat-5.1.lua</tt> must be installed in the <tt>LUA_PATH</tt>.
|
|
If you are using Lua 5.1, nothing should be done.
|
|
</p>
|
|
|
|
|
|
|
|
<h2><a name="data_types"></a>Data types</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<h3><a name="xr2lua"></a>From XML-RPC to Lua</h3>
|
|
|
|
<p>When converting from XML-RPC element to a Lua object, a table
|
|
with a field <code>tag</code> is used. The child elements are
|
|
stored at numbered indexes and white space is ignored.</p>
|
|
|
|
<table border="1">
|
|
<tr>
|
|
<td>XML-RPC data type</td>
|
|
<td>Lua object</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>double<br>
|
|
int<br>
|
|
i4</td>
|
|
<td>number</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>string</td>
|
|
<td>string</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>boolean</td>
|
|
<td>boolean</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>struct<br>
|
|
arrray</td>
|
|
<td>table</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>other elements</td>
|
|
<td>
|
|
<pre>
|
|
{
|
|
tag = "element name",
|
|
[1] = <first child>,
|
|
[2] = <second child>,
|
|
[3] = ...,
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h3><a name="lua2xr"></a>From Lua to XML-RPC</h3>
|
|
|
|
<p>A conversion from a Lua object to an XML-RPC can be made
|
|
automatically or explicitly. The automatic conversion rules
|
|
are:</p>
|
|
|
|
<table border="1">
|
|
<tr>
|
|
<td>Lua object</td>
|
|
<td>XML-RPC data type</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>number</td>
|
|
<td>int or double</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>string</td>
|
|
<td>string</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>boolean</td>
|
|
<td>boolean</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>{ key = val }</code> </td>
|
|
<td>
|
|
<pre>
|
|
<struct>
|
|
<member>
|
|
<name>key</name>
|
|
<value><i>val</i></value>
|
|
</member>
|
|
</struct>
|
|
</pre>
|
|
|
|
<small><i>val</i> is converted according to the same rules.</small>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
In case of a table that has numeric keys, the resulting struct will
|
|
have the string representation of these numbers as keys (e.g.
|
|
<code>"1"</code> instead of <code>1</code>). The library tries to
|
|
convert integral numbers to integer types, otherwise converting
|
|
them to floating point numbers. <!--
|
|
Explicit conversions can be forced by the creation of <i>typed values</i>
|
|
(see function <code><a href="#newtypedvalue">newTypedValue</a></code>).
|
|
-->
|
|
</p>
|
|
|
|
<h2><a name="basic"></a>Basic support</h2>
|
|
|
|
<p>The file <code>xmlrpc.lua</code> implements all basic support
|
|
for encoding and decoding XML-RPC messages and for transforming
|
|
data types between the two representations. Following is the list
|
|
of functions.</p>
|
|
|
|
<ul>
|
|
<li style="list-style: none"><a name="clEncode"></a></li>
|
|
|
|
<li><b><code>clEncode (method_name, params*) =>
|
|
method_call</code></b><br>
|
|
Build a XML-RPC document containing a <code>methodCall</code>
|
|
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. <a name="clDecode"></a></li>
|
|
|
|
<li><b><code>clDecode (method_response) => ok,
|
|
results</code></b><br>
|
|
Disassemble the server response into a Lua object. It receives a
|
|
string containing the XML-RPC document representing the
|
|
<code>methodResponse</code> element. The result is a boolean
|
|
indicating wether the call was successful or not followed by the
|
|
resulting objects (typically a methodResponse has only one value so
|
|
only one Lua object will be returned). In case of error the
|
|
<code>false</code> value is followed by the XMLRPC
|
|
<i>faultString</i> and the <i>faultCode</i>. This values are
|
|
extracted from the <code>fault</code> element. <a name=
|
|
"srvDecode"></a></li>
|
|
|
|
<li><b><code>srvDecode (method_call) => method_name,
|
|
list_params</code></b><br>
|
|
Disassemble the client request into a method's name and a table
|
|
with the list of parameters. It receives a string containing the
|
|
XML-RPC document representing the <code>methodCall</code> element.
|
|
The result is a string with the name of the method to be called and
|
|
a Lua table with the arguments to the call. <a name=
|
|
"srvEncode"></a></li>
|
|
|
|
<li><b><code>srvEncode (object, is_fault) =>
|
|
method_response</code></b><br>
|
|
Build a XML-RPC document containing a <code>methodResponse</code>
|
|
element. It receives a Lua object (a number, a string, a table, a
|
|
"created typed value" etc.) with the return value of the call. The
|
|
result is a string containing the XML-RPC document. Note that
|
|
XML-RPC defines that a response only returns <i>one</i> value so a
|
|
Lua function that returns more than one value has to <i>pack</i>
|
|
them into a table to guarantee that all of them will be returned.
|
|
The second parameter (<code>is_fault</code>) can be used to force a
|
|
<code>fault</code> element to be generated instead of a
|
|
<code>params</code>. In this case, the Lua object must be a table
|
|
with the members <code>faultCode</code> and
|
|
<code>faultString</code>. <!--
|
|
<a name="newtypedvalue"></a>
|
|
<li> <b><code>newTypedValue (object, type) => object</code></b> <br>
|
|
Build a Lua object with the XML-RPC representation of the Lua
|
|
<code>object</code> given according to the given <code>type</code>.
|
|
|
|
<a name="newarray"></a>
|
|
<li> <b><code>newArray (elemtype) => type</code></b> <br>
|
|
Build an array type for use with
|
|
<a href="newtypedvalue">newTypedValue</a>
|
|
function.
|
|
The <code>elemtype</code> can be one of the basic XML-RPC types or
|
|
a constructed one.
|
|
-->
|
|
<a name="srvMethods"></a></li>
|
|
|
|
<li><b><code>srvMethods (tab_or_func)</code></b><br>
|
|
Register the methods on the server. The parameter can be a table
|
|
or a dispatching function. If a <i>table</i> is given it can have
|
|
one level of objects with the corresponding methods. If a
|
|
<i>function</i> is given, it will replace the dispatcher. <a name=
|
|
"dispatch"></a></li>
|
|
|
|
<li><b><code>dispatch (method_name) => function</code></b><br>
|
|
Returns a Lua function that implements the method call. Note that
|
|
the object is encapsulated into that function so that the call will
|
|
be turned into a real method call.</li>
|
|
</ul>
|
|
|
|
|
|
<h2><a name="client"></a>Client side</h2>
|
|
|
|
<p>The file <code>xmlrpc.http.lua</code> implements a simple
|
|
stand-alone client based on <a href=
|
|
"http://www.tecgraf.puc-rio.br/luasocket">LuaSocket 2.0</a>. The
|
|
following function is provided:</p>
|
|
|
|
<ul>
|
|
<li style="list-style: none"><a name="call"></a></li>
|
|
|
|
<li><b><code>call (url, method, params*)</code></b><br>
|
|
Execute the call to <code>method</code> at location
|
|
<code>url</code> with the given <code>params</code> (if any). The
|
|
<code>method</code> and <code>params</code> parameters will be just
|
|
passed to <a href="#clEncode">clEncode</a> function. The result is
|
|
the same as <a href="#clDecode">clDecode</a> function: a boolean
|
|
indicating whether the call was successful or not, followed by the
|
|
response value (if successful) or by the <i>faultString</i> and the
|
|
<i>faultCode</i> (if the call fails). <!--
|
|
The result is a boolean indicating whether the call was successful or
|
|
not, followed by the response value (if successful) or by the faultString
|
|
and the faultCode (if the call fails).
|
|
-->
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<h2><a name="server"></a>Server side</h2>
|
|
|
|
<p>The distribution also offers a simple XML-RPC server implemented
|
|
over a CGI launcher. This launcher just have to offer a way to
|
|
decode POST data and to send data back to the client.</p>
|
|
|
|
<p>The file <code>xmlrpc.cgi.lua</code> implements a simple XML-RPC
|
|
server using the package <code>post</code> that can parse incoming
|
|
POST data from the http server. An appropriate environment for
|
|
writing Lua functions is implemented; a new <code>assert</code>
|
|
function generates a XML-RPC fault in case of a false condition; a
|
|
<code>respond</code> function creates the correct header for the
|
|
responses.</p>
|
|
|
|
<p>The main goal of this file is to give a starting point for other
|
|
real implementations.</p>
|
|
|
|
|
|
<h2><a name="references"></a>References</h2>
|
|
|
|
<p>
|
|
Here is a list of related documentation:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="http://www.xmlrpc.com">http://www.xmlrpc.com</a></li>
|
|
</ul>
|
|
|
|
</div> <!-- id="content" -->
|
|
|
|
</div> <!-- id="main" -->
|
|
|
|
<div id="about">
|
|
<p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
|
|
<p><small>
|
|
$Id$
|
|
</small></p>
|
|
</div> <!-- id="about" -->
|
|
|
|
</div> <!-- id="container" -->
|
|
|
|
</body>
|
|
</html>
|