CiaranG
/
lua-xmlrpc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated documentation

master
Tim Niemueller 2010-10-18 17:50:45 -04:00
parent f5d4ffdabd
commit 6a0087d1ae
9 changed files with 782 additions and 742 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

215
doc/examples.html Executable file
View File

@ -0,0 +1,215 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Lua XML-RPC: 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="Lua XML-RPC logo" src="luaxmlrpc.png"/>
</a>
</div>
<div id="product_name"><big><b>Lua XML-RPC</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>Lua XML-RPC</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><a href="manual.html">Manual</a>
<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#functions">Library functions</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><strong>Examples</strong></li>
<li><a href="license.html">License</a></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2><a name="examples"></a>Examples</h2>
<h3><a name="client_example"></a>Client example</h3>
<p>Below is a small sample code displaying the use of the library in a
client application.</p>
<pre class="example">
require "xmlrpc.http"
local ok, res = xmlrpc.http.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
</pre>
<h3><a name="types_example"></a>Type conversion example</h3>
<p>The next example shows how to force the conversion of types from
Lua to XML-RPC.</p>
<pre class="example">
require "xmlrpc"
double_array_type = xmlrpc.newArray ("double")
double_array = xmlrpc.newTypedValue ( { 1.1, 2, 3, 4 }, double_array_type)
double_array_array_type = xmlrpc.newArray (double_array_type)
double_array_array = xmlrpc.newTypedValue (
{
{ 11, 12, 13, },
{ 21, 22, 23, },
{ 31, 32, 33, },
}, double_array_array_type)
</pre>
<p>The table <code>double_array_array</code> will be:</p>
<pre class="example">
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;&lt;double&gt;11&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;12&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;13&lt;/double&gt;&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
&lt;/value&gt;
&lt;value&gt;
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;&lt;double&gt;21&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;22&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;23&lt;/double&gt;&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
&lt;/value&gt;
&lt;value&gt;
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;&lt;double&gt;31&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;32&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;33&lt;/double&gt;&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
</pre>
<h3><a name="server_example"></a>Server example</h3>
<p>Follows a small example of a server based on Xavante
WSAPI. You can call the service for example with
the <code>xmlrpc</code> tool
from <a href="http://xmlrpc-c.sourceforge.net/">XML-RPC
C</a> (<code>xmlrpc http://localhost:12345
hello_world</code>) or by
using <code>examples/client.lua</code> in the source
tarball.</p>
<pre class="example">
require("xavante")
require("xavante.httpd")
require("wsapi.xavante")
require("wsapi.request")
require("xmlrpc")
--- XML-RPC WSAPI handler
-- @param wsapi_env WSAPI environment
function wsapi_handler(wsapi_env)
local headers = { ["Content-type"] = "text/xml" }
local req = wsapi.request.new(wsapi_env)
local method, arg_table = xmlrpc.srvDecode(req.POST.post_data)
local func = xmlrpc.dispatch(method)
local result = { pcall(func, unpack(arg_table or {})) }
local ok = result[1]
if not ok then
result = { code = 3, message = result[2] }
else
table.remove(result, 1)
if table.getn(result) == 1 then
result = result[1]
end
end
local r = xmlrpc.srvEncode(result, not ok)
headers["Content-length"] = tostring(#r)
local function xmlrpc_reply(wsapienv)
coroutine.yield(r)
end
return 200, headers, coroutine.wrap(xmlrpc_reply)
end
-- XML-RPC exported functions
xmlrpc_exports = {}
--- Get simple string.
-- @return simple string
function xmlrpc_exports.hello_world()
return "Hello World"
end
local rules = {{ match = ".", with = wsapi.xavante.makeHandler(wsapi_handler) }}
local config = { server = {host = "*", port = 12345}, defaultHost = { rules = rules} }
xmlrpc.srvMethods(xmlrpc_exports)
xavante.HTTP(config)
xavante.run()
</pre>
<p>Note that the package <code>post</code> and the function
<code>respond</code> should be provided by the cgi launcher.</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

134
doc/index.html Executable file
View File

@ -0,0 +1,134 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Lua XML-RPC: 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="Lua XML-RPC logo" src="luaxmlrpc.png"/>
</a>
</div>
<div id="product_name"><big><b>Lua XML-RPC</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>Lua XML-RPC</h1>
<ul>
<li><strong>Home</strong>
<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><a href="manual.html">Manual</a>
<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#functions">Library functions</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="overview"></a>Overview</h2>
<p>Lua XML-RPC is a library to make remote procedure calls using
<a href="http://www.xmlrpc.com">XML-RPC</a>. It also offers facilities
to develop server-side software.</p>
<p>Lua XML-RPC provides a simple API and an abstraction layer over XML,
thus avoiding the complexity of having to deal with strings that
represent data structures.</p>
<p>Lua XML-RPC is free software and uses the same
<a href="license.html">license</a> as Lua 5.1.</p>
<h2><a name="status"></a>Status</h2>
<p>Current version is 1.2. It was developed for Lua 5.1 based on
<a href="http://www.keplerproject.org/luaexpat">LuaExpat</a>.</p>
<h2><a name="download"></a>Download</h2>
<p>Lua XML-RPC can be downloaded in source code from
<a href="http://github.com/timn/lua-xmlrpc">Github</a>.</p>
<h2><a name="history"></a>History</h2>
<dl>
<dt><strong>Version 1.2</strong> [18/oct/2010] (timn)</dt>
<dd>Lua 5.1 compatibility, converted from CVS to git,
patches to improve handling or errorneous data</dd>
<dt><strong>Version 1.0</strong> [23/jan/2006]</dt>
<dd />
<dt><strong>Version 1.0 Beta</strong> [2/dec/2004]</dt>
<dd />
<dt><strong>Version 1.0 Alpha</strong> [10/dec/2003]</dt>
<dd />
</dl>
<p>Lua XML-RPC Version 1.2 follows the
<a href="http://www.keplerproject.org/compat">package model</a>
for Lua 5.1 (see section <a href="manual.html#installation">Installation</a>
for more details).</p>
<h2><a name="credits"></a>Credits</h2>
<p>Lua XML-RPC was designed by Roberto Ierusalimschy, Andr&eacute;
Carregal and Tom&aacute;s Guisasola as part of the
<a href="http://www.keplerproject.org">Kepler Project</a>
which holds its copyright. It was initially implemented by
Tom&aacute;s Guisasola.
<a href="http://www.niemueller.de">Tim Niemueller</a> is
the current maintainer.</a></p>
<p>Lua XML-RPC initial development was sponsored by
<a href="http://www.fabricadigital.com.br">F&aacute;brica Digital</a>
and FINEP.</p>
<h2><a name="contact"></a>Contact</h2>
<p>For more information please
<a href="mailto:info-NO-SPAM-THANKS@keplerproject.org">contact us</a>.
Comments are welcome!</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

113
doc/license.html Executable file
View File

@ -0,0 +1,113 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Lua XML-RPC: 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="Lua XML-RPC logo" src="luaxmlrpc.png"/>
</a></div>
<div id="product_name"><big><b>Lua XML-RPC</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>Lua XML-RPC</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><a href="manual.html">Manual</a>
<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#functions">Library functions</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><strong>License</strong></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2>License</h2>
<p>
Lua XML-RPC is free software: it can be used for both academic and
commercial purposes at absolutely no cost. There are no royalties
or GNU-like "copyleft" restrictions. Lua XML-RPC qualifies as <a
href="http://www.opensource.org/docs/definition.html">Open
Source</a> software. Its licenses are compatible with <a href=
"http://www.gnu.org/licenses/gpl.html">GPL</a>. Lua XML-RPC is not in
the public domain and the <a href="http://www.keplerproject.org">
Kepler Project</a> hold its copyright. The legal details are below.
</p>
<p>The spirit of the license is that you are free to use Lua XML-RPC
for any purpose at no cost without having to ask us. The only
requirement is that if you do use Lua XML-RPC, then you should give
us credit by including the appropriate copyright notice somewhere
in your product or its documentation.</p>
<p>The Lua XML-RPC library is designed and implemented by Roberto
Ierusalimschy, Andr&eacute; Carregal and Tom&aacute;s
Guisasola. Tim Niemueller is the current maintainer.
The implementation is not derived from licensed software.</p>
<hr/>
<p>
Copyright &copy; 2003-2010 Kepler Project.
</p>
<p>Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

0
doc/us/luaxmlrpc.png → doc/luaxmlrpc.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.1 KiB

After

Width:  |  Height:  |  Size: 8.1 KiB

320
doc/manual.html Executable file
View File

@ -0,0 +1,320 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Lua XML-RPC: 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="Lua XML-RPC logo" src="luaxmlrpc.png"/>
</a>
</div>
<div id="product_name"><big><strong>Lua XML-RPC</strong></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>Lua XML-RPC</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#functions">Library functions</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>Lua XML-RPC is a <a href="http://www.lua.org">Lua</a> library that can be used
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 handling XML code</li>
<li>Transform Lua data structures into XML-RPC data types and vice-versa</li>
</ul>
<p>Lua XML-RPC provides a simple API and an abstraction layer over XML avoiding
manipulation of string representation of data structures.</p>
<p>Lua XML-RPC is based on
<a href="http://www.keplerproject.org/luaexpat">LuaExpat</a> and on
<a href="http://www.lua.org">Lua 5.1</a>.
The abstraction layer over HTTP depends on
<a href="http://w3.impa.br/~diego/software/luasocket/">LuaSocket 2.0.2</a>.</p>
<h2><a name="installation"></a>Installation</h2>
<p>Lua XML-RPC is composed by three Lua files:
<dl>
<dt><code>init.lua</code></dt>
<dd>Main source file providing the API</dd>
<dt><code>http.lua</code></dt>
<dd>API to call XML-RPC via HTTP</dd>
<dt><code>server.lua</code></dt>
<dd>Server side API</dd>
</dl>
</p>
These files should be copied to a directory named <code>xmlrpc</code> created in your
<code>LUA_PATH</code>.</p>
<p>Lua XML-RPC follows the
<a href="http://www.keplerproject.org/compat/">package model</a>
for Lua 5.1, therefore it should be "installed". Refer to
<a href="http://www.keplerproject.org/compat/manual.html#configuration">
Compat-5.1 configuration</a> section about how to install the module.</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 data item or table,
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>
<tr>
<th>XML-RPC data type(s)</th>
<th>Lua object</th>
</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] = &lt;first child&gt;,
[2] = &lt;second child&gt;,
[3] = ...,
}</pre>
</td>
</tr>
</table>
<h3><a name="lua2xr"></a>From Lua to XML-RPC</h3>
<p>A conversion from a Lua data item or table to an XML-RPC element
can be made automatically or explicitly. The automatic conversion rules
are:</p>
<table>
<tr>
<th>Lua object</th>
<th>XML-RPC data type</th>
</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>
&lt;struct&gt;
&lt;member&gt;
&lt;name&gt;key&lt;/name&gt;
&lt;value&gt;<em>val</em>&lt;/value&gt;
&lt;/member&gt;
&lt;/struct&gt;
</pre>
<small><em>val</em> is converted according to the same rules.</small>
</td>
</tr>
</table>
<p>Ifn 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.</p>
<h2><a name="functions"></a>Library functions</h2>
<p>The <code>xmlrpc.lua</code> file implements the functions that encode and decode XML-RPC messages and transform
data types between the Lua and XML-RPC. The functions are:</p>
<dl>
<dt><a name="clEncode"></a><strong><code>clEncode (method_name [, params]) =&gt; method_call</code></strong></dt>
<dd>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.</dd>
<dt><a name="clDecode"></a><strong><code>clDecode (method_response) =&gt; ok, results</code></strong></dt>
<dd>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
<em>faultString</em> and the <em>faultCode</em>. This values are
extracted from the <code>fault</code> element.</dd>
<dt><a name="srvDecode"></a><strong><code>srvDecode (method_call) =&gt; method_name, list_params</code></strong></dt>
<dd>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.</dd>
<dt><a name="srvEncode"></a><strong><code>srvEncode (object, is_fault) =&gt; method_response</code></strong></dt>
<dd>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 <em>one</em> value so a
Lua function that returns more than one value has to <em>pack</em>
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>.</dd>
<dt><a name="srvMethods"></a><strong><code>srvMethods (tab_or_func)</code></strong></dt>
<dd>Register the methods on the server. The parameter can be a table
or a dispatching function. If a <em>table</em> is given it can have
one level of objects with the corresponding methods. If a
<em>function</em> is given, it will replace the dispatcher.</dd>
<dt><a name="dispatch"></a><strong><code>dispatch (method_name) =&gt; function</code></strong></dt>
<dd>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.</dd>
</dl>
<h2><a name="client"></a>Client side</h2>
<p>The <code>http.lua</code> file implements a simple
stand-alone client based on
<a href="http://w3.impa.br/~diego/software/luasocket/">LuaSocket 2.0.2</a>. The
following function is provided:</p>
<dl>
<dt><a name="call"></a><strong><code>call (url, method [, params])</code></strong></dt>
<dd>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 <em>faultString</em> and the
<em>faultCode</em> (if the call fails).</dd>
</dl>
<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 <code>tests</code> directory contains a file named
<code>cgi.lua</code>, which implements an example of a simple XML-RPC
server using the package <code>post</code> (which parses 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. The main goal of <code>cgi.lua</code> is to give a
starting point for other implementations.</p>
<h2><a name="references"></a>References</h2>
<p>Related documentation can be found at: <a href="http://www.xmlrpc.com">http://www.xmlrpc.com</a>.</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

186
doc/us/examples.html
View File

@ -1,186 +0,0 @@
<!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><a href="manual.html">Manual</a>
<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#functions">Library functions</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><strong>Examples</strong></li>
<li><a href="license.html">License</a></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2><a name="examples"></a>Examples</h2>
<h3><a name="client_example"></a>Client example</h3>
<p>Below is a small sample code displaying the use of the library in a
client application.</p>
<pre class="example">
require "xmlrpc.http"
local ok, res = xmlrpc.http.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
</pre>
<h3><a name="types_example"></a>Type conversion example</h3>
<p>The next example shows how to force the conversion of types from
Lua to XML-RPC.</p>
<pre class="example">
require "xmlrpc"
double_array_type = xmlrpc.newArray ("double")
double_array = xmlrpc.newTypedValue ( { 1.1, 2, 3, 4 }, double_array_type)
double_array_array_type = xmlrpc.newArray (double_array_type)
double_array_array = xmlrpc.newTypedValue (
{
{ 11, 12, 13, },
{ 21, 22, 23, },
{ 31, 32, 33, },
}, double_array_array_type)
</pre>
<p>The table <code>double_array_array</code> will be:</p>
<pre class="example">
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;&lt;double&gt;11&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;12&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;13&lt;/double&gt;&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
&lt;/value&gt;
&lt;value&gt;
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;&lt;double&gt;21&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;22&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;23&lt;/double&gt;&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
&lt;/value&gt;
&lt;value&gt;
&lt;array&gt;
&lt;data&gt;
&lt;value&gt;&lt;double&gt;31&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;32&lt;/double&gt;&lt;/value&gt;
&lt;value&gt;&lt;double&gt;33&lt;/double&gt;&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
&lt;/value&gt;
&lt;/data&gt;
&lt;/array&gt;
</pre>
<h3><a name="server_example"></a>Server example</h3>
<p>Follows a small example of a server based on a cgi launcher.</p>
<pre class="example">
require "xmlrpc.cgi"
local kepler_home = "http://www.keplerproject.org"
local kepler_products = { "luasql", "lualdap", "luaexpat", "luaxmlrpc", }
local kepler_sites = {
luasql = kepler_home.."/luasql",
lualdap = kepler_home.."/lualdap",
luaexpat = kepler_home.."/luaexpat",
luaxmlrpc = kepler_home.."/luaxmlrpc",
}
-- Register methods
xmlrpc.srvMethods {
kepler = {
products = function (self) return kepler_products end,
site = function (self, prod) return kepler_sites[prod] end,
}
}
-- Parse POST data
local doc = {}
post.parsedata (doc)
-- Decode method call
local method, arg_table = xmlrpc.srvDecode (doc[1])
local func = xmlrpc.dispatch (method)
local ok, result, err = pcall (func, unpack (arg_table or {}))
if ok then
result = { code = 3, message = result, }
end
respond (xmlrpc.srvEncode (result, not ok))
</pre>
<p>Note that the package <code>post</code> and the function
<code>respond</code> should be provided by the cgi launcher.</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

129
doc/us/index.html
View File

@ -1,129 +0,0 @@
<!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><strong>Home</strong>
<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><a href="manual.html">Manual</a>
<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#functions">Library functions</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="overview"></a>Overview</h2>
<p>LuaXMLRPC is a library to make remote procedure calls using
<a href="http://www.xmlrpc.com">XML-RPC</a>. It also offers facilities
to develop server-side software.</p>
<p>LuaXMLRPC provides a simple API and an abstraction layer over XML,
thus avoiding the complexity of having to deal with strings that
represent data structures.</p>
<p>LuaXMLRPC is free software and uses the same
<a href="license.html">license</a> as Lua 5.0.</p>
<h2><a name="status"></a>Status</h2>
<p>Current version is 1.0. It was developed for Lua 5.0 based on
<a href="http://www.keplerproject.org/luaexpat">LuaExpat</a>.</p>
<h2><a name="download"></a>Download</h2>
<p>LuaXMLRPC can be downloaded in source code from its
<a href="http://luaforge.net/frs/?group_id=16">LuaForge</a> page.</p>
<h2><a name="history"></a>History</h2>
<dl>
<dt><strong>Version 1.0</strong> [23/jan/2006]</dt>
<dd />
<dt><strong>Version 1.0 Beta</strong> [2/dec/2004]</dt>
<dd />
<dt><strong>Version 1.0 Alpha</strong> [10/dec/2003]</dt>
<dd />
</dl>
<p>LuaXMLRPC Version 1.0 follows the
<a href="http://www.keplerproject.org/compat">package model</a>
for Lua 5.1 (see section <a href="manual.html#installation">Installation</a>
for more details).</p>
<h2><a name="credits"></a>Credits</h2>
<p>LuaXMLRPC was designed by Roberto Ierusalimschy, Andr&eacute;
Carregal and Tom&aacute;s Guisasola as part of the
<a href="http://www.keplerproject.org">Kepler Project</a>
which holds its copyright. It was implemented by Tom&aacute;s Guisasola.</p>
<p>LuaXMLRPC development was sponsored by
<a href="http://www.fabricadigital.com.br">F&aacute;brica Digital</a>
and FINEP.</p>
<h2><a name="contact"></a>Contact</h2>
<p>For more information please
<a href="mailto:info-NO-SPAM-THANKS@keplerproject.org">contact us</a>.
Comments are welcome!</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

112
doc/us/license.html
View File

@ -1,112 +0,0 @@
<!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><a href="manual.html">Manual</a>
<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#functions">Library functions</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><strong>License</strong></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2>License</h2>
<p>
LuaXMLRPC is free software: it can be used for both academic and
commercial purposes at absolutely no cost. There are no royalties
or GNU-like "copyleft" restrictions. LuaXMLRPC qualifies as <a
href="http://www.opensource.org/docs/definition.html">Open
Source</a> software. Its licenses are compatible with <a href=
"http://www.gnu.org/licenses/gpl.html">GPL</a>. LuaXMLRPC is not in
the public domain and the <a href="http://www.keplerproject.org">
Kepler Project</a> hold its copyright. The legal details are below.
</p>
<p>The spirit of the license is that you are free to use LuaXMLRPC
for any purpose at no cost without having to ask us. The only
requirement is that if you do use LuaXMLRPC, then you should give
us credit by including the appropriate copyright notice somewhere
in your product or its documentation.</p>
<p>The LuaXMLRPC library is designed and implemented by Roberto
Ierusalimschy, Andr&eacute; Carregal and Tom&aacute;s Guisasola.
The implementation is not derived from licensed software.</p>
<hr/>
<p>
Copyright &copy; 2003-2006 Kepler Project.
</p>
<p>Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

315
doc/us/manual.html
View File

@ -1,315 +0,0 @@
<!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><strong>LuaXMLRPC</strong></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#functions">Library functions</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 that can be used
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 handling XML code</li>
<li>Transform Lua data structures 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.</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:</p>
<ul>
<li><code>xmlrpc.lua</code></li>
<li><b>FALTA COLOCAR OS NOMES DOS OUTROS ARQUIVOS</b></li>
</ul>
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 it should be "installed". Refer to
<a href="http://www.keplerproject.org/compat/manual.html#configuration">
Compat-5.1 configuration</a> section about how to install the module.</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 data item or table,
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>
<tr>
<th>XML-RPC data type(s)</th>
<th>Lua object</th>
</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] = &lt;first child&gt;,
[2] = &lt;second child&gt;,
[3] = ...,
}</pre>
</td>
</tr>
</table>
<h3><a name="lua2xr"></a>From Lua to XML-RPC</h3>
<p>A conversion from a Lua data item or table to an XML-RPC element
can be made automatically or explicitly. The automatic conversion rules
are:</p>
<table>
<tr>
<th>Lua object</th>
<th>XML-RPC data type</th>
</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>
&lt;struct&gt;
&lt;member&gt;
&lt;name&gt;key&lt;/name&gt;
&lt;value&gt;<em>val</em>&lt;/value&gt;
&lt;/member&gt;
&lt;/struct&gt;
</pre>
<small><em>val</em> is converted according to the same rules.</small>
</td>
</tr>
</table>
<p>Ifn 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.</p>
<h2><a name="functions"></a>Library functions</h2>
<p>The <code>xmlrpc.lua</code> file implements the functions that encode and decode XML-RPC messages and transform
data types between the Lua and XML-RPC. The functions are:</p>
<dl>
<dt><a name="clEncode"></a><strong><code>clEncode (method_name [, params]) =&gt; method_call</code></strong></dt>
<dd>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.</dd>
<dt><a name="clDecode"></a><strong><code>clDecode (method_response) =&gt; ok, results</code></strong></dt>
<dd>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
<em>faultString</em> and the <em>faultCode</em>. This values are
extracted from the <code>fault</code> element.</dd>
<dt><a name="srvDecode"></a><strong><code>srvDecode (method_call) =&gt; method_name, list_params</code></strong></dt>
<dd>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.</dd>
<dt><a name="srvEncode"></a><strong><code>srvEncode (object, is_fault) =&gt; method_response</code></strong></dt>
<dd>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 <em>one</em> value so a
Lua function that returns more than one value has to <em>pack</em>
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>.</dd>
<dt><a name="srvMethods"></a><strong><code>srvMethods (tab_or_func)</code></strong></dt>
<dd>Register the methods on the server. The parameter can be a table
or a dispatching function. If a <em>table</em> is given it can have
one level of objects with the corresponding methods. If a
<em>function</em> is given, it will replace the dispatcher.</dd>
<dt><a name="dispatch"></a><strong><code>dispatch (method_name) =&gt; function</code></strong></dt>
<dd>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.</dd>
</dl>
<h2><a name="client"></a>Client side</h2>
<p>The <code>http.lua</code> file 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>
<dl>
<dt><a name="call"></a><strong><code>call (url, method [, params])</code></strong></dt>
<dd>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 <em>faultString</em> and the
<em>faultCode</em> (if the call fails).</dd>
</dl>
<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 <code>tests</code> directory contains a file named
<code>cgi.lua</code>, which implements an example of a simple XML-RPC
server using the package <code>post</code> (which parses 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. The main goal of <code>cgi.lua</code> is to give a
starting point for other implementations.</p>
<h2><a name="references"></a>References</h2>
<p>Related documentation can be found at: <a href="http://www.xmlrpc.com">http://www.xmlrpc.com</a>.</p>
</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>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>