From 6a0087d1ae7a4ae0fa5751db2a7fbd67e231918c Mon Sep 17 00:00:00 2001 From: Tim Niemueller Date: Mon, 18 Oct 2010 17:50:45 -0400 Subject: [PATCH] Updated documentation --- doc/examples.html | 215 +++++++++++++++++++++++++ doc/index.html | 134 ++++++++++++++++ doc/license.html | 113 +++++++++++++ doc/{us => }/luaxmlrpc.png | Bin doc/manual.html | 320 +++++++++++++++++++++++++++++++++++++ doc/us/examples.html | 186 --------------------- doc/us/index.html | 129 --------------- doc/us/license.html | 112 ------------- doc/us/manual.html | 315 ------------------------------------ 9 files changed, 782 insertions(+), 742 deletions(-) create mode 100755 doc/examples.html create mode 100755 doc/index.html create mode 100755 doc/license.html rename doc/{us => }/luaxmlrpc.png (100%) create mode 100755 doc/manual.html delete mode 100755 doc/us/examples.html delete mode 100755 doc/us/index.html delete mode 100755 doc/us/license.html delete mode 100755 doc/us/manual.html diff --git a/doc/examples.html b/doc/examples.html new file mode 100755 index 0000000..dd60d87 --- /dev/null +++ b/doc/examples.html @@ -0,0 +1,215 @@ + + + + Lua XML-RPC: XML-RPC interface to the Lua programming language + + + + + +
+ +
+ +
Lua XML-RPC
+
XML-RPC interface to the Lua programming language
+
+ +
+ + + +
+ + +

Examples

+ +

Client example

+ +

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

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

Type conversion example

+ +

The next example shows how to force the conversion of types from + Lua to XML-RPC.

+ + 
+	    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)
+
+ +

The table double_array_array will be:

+ + 
+	    <array>
+	    <data>
+	    <value>
+	    <array>
+            <data>
+            <value><double>11</double></value>
+            <value><double>12</double></value>
+            <value><double>13</double></value>
+            </data>
+	    </array>
+	    </value>
+	    <value>
+	    <array>
+            <data>
+            <value><double>21</double></value>
+            <value><double>22</double></value>
+            <value><double>23</double></value>
+            </data>
+	    </array>
+	    </value>
+	    <value>
+	    <array>
+            <data>
+            <value><double>31</double></value>
+            <value><double>32</double></value>
+            <value><double>33</double></value>
+            </data>
+	    </array>
+	    </value>
+	    </data>
+	    </array>
+
+ + + +

Server example

+ +

Follows a small example of a server based on Xavante + WSAPI. You can call the service for example with + the xmlrpc tool + from XML-RPC + C (xmlrpc http://localhost:12345 + hello_world) or by + using examples/client.lua in the source + tarball.

+ + 
+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()
+
+ +

Note that the package post and the function + respond should be provided by the cgi launcher.

+ +
+ +
+ +
+

+ + Valid XHTML 1.0! + +

+
+ +
+ + + diff --git a/doc/index.html b/doc/index.html new file mode 100755 index 0000000..4596ee3 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,134 @@ + + + + + Lua XML-RPC: XML-RPC interface to the Lua programming language + + + + + + +
+ +
+ +
Lua XML-RPC
+
XML-RPC interface to the Lua programming language
+
+ +
+ + + +
+ +

Overview

+ +

Lua XML-RPC is a library to make remote procedure calls using + XML-RPC. It also offers facilities + to develop server-side software.

+ +

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.

+ +

Lua XML-RPC is free software and uses the same + license as Lua 5.1.

+ +

Status

+ +

Current version is 1.2. It was developed for Lua 5.1 based on + LuaExpat.

+ +

Download

+ +

Lua XML-RPC can be downloaded in source code from + Github.

+ +

History

+ +
+
Version 1.2 [18/oct/2010] (timn)
+
Lua 5.1 compatibility, converted from CVS to git, + patches to improve handling or errorneous data
+
Version 1.0 [23/jan/2006]
+
+
Version 1.0 Beta [2/dec/2004]
+
+
Version 1.0 Alpha [10/dec/2003]
+
+
+ +

Lua XML-RPC Version 1.2 follows the + package model + for Lua 5.1 (see section Installation + for more details).

+ +

Credits

+ +

Lua XML-RPC was designed by Roberto Ierusalimschy, André + Carregal and Tomás Guisasola as part of the + Kepler Project + which holds its copyright. It was initially implemented by + Tomás Guisasola. + Tim Niemueller is + the current maintainer.

+ +

Lua XML-RPC initial development was sponsored by + Fábrica Digital + and FINEP.

+ +

Contact

+ +

For more information please + contact us. + Comments are welcome!

+ +
+ +
+ +
+

+ + Valid XHTML 1.0! + +

+
+
+ + + diff --git a/doc/license.html b/doc/license.html new file mode 100755 index 0000000..bc188ac --- /dev/null +++ b/doc/license.html @@ -0,0 +1,113 @@ + + + + Lua XML-RPC: XML-RPC interface to the Lua programming language + + + + + +
+ +
+ +
Lua XML-RPC
+
XML-RPC interface to the Lua programming language
+
+ +
+ + + +
+ +

License

+ +

+ 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 Open + Source software. Its licenses are compatible with GPL. Lua XML-RPC is not in + the public domain and the + Kepler Project hold its copyright. The legal details are below. +

+ +

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.

+ +

The Lua XML-RPC library is designed and implemented by Roberto + Ierusalimschy, André Carregal and Tomás + Guisasola. Tim Niemueller is the current maintainer. + The implementation is not derived from licensed software.

+ +
+

+ Copyright © 2003-2010 Kepler Project. +

+

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:

+ +

The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software.

+ +

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.

+ +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + + diff --git a/doc/us/luaxmlrpc.png b/doc/luaxmlrpc.png similarity index 100% rename from doc/us/luaxmlrpc.png rename to doc/luaxmlrpc.png diff --git a/doc/manual.html b/doc/manual.html new file mode 100755 index 0000000..a05730c --- /dev/null +++ b/doc/manual.html @@ -0,0 +1,320 @@ + + + + Lua XML-RPC: XML-RPC interface to the Lua programming language + + + + + +
+ +
+ +
Lua XML-RPC
+
XML-RPC interface to the Lua programming language
+
+ +
+ + + +
+ +

Introduction

+ +

Lua XML-RPC is a Lua library that can be used + to build XML-RPC clients and + servers. It enables a Lua program to:

+ +
    +
  • Encode and decode XML-RPC messages without handling XML code
    • +
  • Transform Lua data structures into XML-RPC data types and vice-versa
    • +
+ +

Lua XML-RPC provides a simple API and an abstraction layer over XML avoiding + manipulation of string representation of data structures.

+ +

Lua XML-RPC is based on + LuaExpat and on + Lua 5.1. + The abstraction layer over HTTP depends on + LuaSocket 2.0.2.

+ +

Installation

+ +

Lua XML-RPC is composed by three Lua files: + +

+
init.lua
+
Main source file providing the API
+
http.lua
+
API to call XML-RPC via HTTP
+
server.lua
+
Server side API
+
+

+ + These files should be copied to a directory named xmlrpc created in your + LUA_PATH.

+ +

Lua XML-RPC follows the + package model + for Lua 5.1, therefore it should be "installed". Refer to + + Compat-5.1 configuration section about how to install the module.

+ +

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 data item or table, + 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(s)Lua object
+ double
+ int
+ i4 + 		number
stringstring
booleanboolean
+ struct
+ arrray + 		table
other elements + 
{
+		tag = "element name",
+		[1] = <first child>,
+		[2] = <second child>,
+		[3] = ...,
+		}
+
+ + +

From Lua to XML-RPC

+ +

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:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Lua objectXML-RPC data type
numberint or double
stringstring
booleanboolean
{ key = val } + 
+		<struct>
+		<member>
+		<name>key</name>
+		<value>val</value>
+		</member>
+		</struct>
+
+ val is converted according to the same rules. +
+ +

Ifn case of a table that has numeric keys, the resulting struct will + have the string representation of these numbers as keys (e.g. + "1" instead of 1). The library tries to + convert integral numbers to integer types, otherwise converting + them to floating point numbers.

+ +

Library functions

+ +

The xmlrpc.lua file implements the functions that encode and decode XML-RPC messages and transform + data types between the Lua and XML-RPC. The functions are:

+ +
+
clEncode (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.
+ +
clDecode (method_response) => ok, 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 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 + false value is followed by the XMLRPC + faultString and the faultCode. This values are + extracted from the fault element.
+ +
srvDecode (method_call) => method_name, list_params
+
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 methodCall 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.
+ +
srvEncode (object, is_fault) => method_response
+
Build a XML-RPC document containing a methodResponse + 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 one value so a + Lua function that returns more than one value has to pack + them into a table to guarantee that all of them will be returned. + The second parameter (is_fault) can be used to force a + fault element to be generated instead of a + params. In this case, the Lua object must be a table + with the members faultCode and + faultString.
+ +
srvMethods (tab_or_func)
+
Register the methods on the server. The parameter can be a table + or a dispatching function. If a table is given it can have + one level of objects with the corresponding methods. If a + function is given, it will replace the dispatcher.
+ +
dispatch (method_name) => function
+
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.
+
+ + +

Client side

+ +

The http.lua file implements a simple + stand-alone client based on + LuaSocket 2.0.2. The + following function is provided:

+ +
+
call (url, method [, params])
+
Execute the call to method at location + url with the given params (if any). The + method and params parameters will be just + passed to clEncode function. The result is + the same as clDecode function: 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).
+
+ + +

Server side

+ +

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.

+ +

The tests directory contains a file named + cgi.lua, which implements an example of a simple XML-RPC + server using the package post (which parses incoming + POST data from the http server). An appropriate environment for + writing Lua functions is implemented; a new assert + function generates a XML-RPC fault in case of a false condition; a + respond function creates the correct header for the + responses. The main goal of cgi.lua is to give a + starting point for other implementations.

+ + +

References

+ +

Related documentation can be found at: http://www.xmlrpc.com.

+ +
+ +
+ +
+

+ + Valid XHTML 1.0! + +

+
+ +
+ + + diff --git a/doc/us/examples.html b/doc/us/examples.html deleted file mode 100755 index 4079d2c..0000000 --- a/doc/us/examples.html +++ /dev/null @@ -1,186 +0,0 @@ - - - - LuaXMLRPC: XML-RPC interface to the Lua programming language - - - - - -
- -
- -
LuaXMLRPC
-
XML-RPC interface to the Lua programming language
-
- -
- - - -
- - -

Examples

- -

Client example

- -

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

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

Type conversion example

- -

The next example shows how to force the conversion of types from -Lua to XML-RPC.

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

The table double_array_array will be:

- -
-<array>
-  <data>
-    <value>
-      <array>
-        <data>
-          <value><double>11</double></value>
-          <value><double>12</double></value>
-          <value><double>13</double></value>
-        </data>
-      </array>
-    </value>
-    <value>
-      <array>
-        <data>
-          <value><double>21</double></value>
-          <value><double>22</double></value>
-          <value><double>23</double></value>
-        </data>
-      </array>
-    </value>
-    <value>
-      <array>
-        <data>
-          <value><double>31</double></value>
-          <value><double>32</double></value>
-          <value><double>33</double></value>
-        </data>
-      </array>
-    </value>
-  </data>
-</array>
-
- - - -

Server example

- -

Follows a small example of a server based on a cgi launcher.

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

Note that the package post and the function -respond should be provided by the cgi launcher.

- -
- -
- -
-

- - Valid XHTML 1.0! - -

-
- -
- - - diff --git a/doc/us/index.html b/doc/us/index.html deleted file mode 100755 index 5a3ee79..0000000 --- a/doc/us/index.html +++ /dev/null @@ -1,129 +0,0 @@ - - - - - LuaXMLRPC: XML-RPC interface to the Lua programming language - - - - - - -
- -
- -
LuaXMLRPC
-
XML-RPC interface to the Lua programming language
-
- -
- - - -
- -

Overview

- -

LuaXMLRPC is a library to make remote procedure calls using -XML-RPC. It also offers facilities -to develop server-side software.

- -

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.

- -

LuaXMLRPC is free software and uses the same -license as Lua 5.0.

- -

Status

- -

Current version is 1.0. It was developed for Lua 5.0 based on -LuaExpat.

- -

Download

- -

LuaXMLRPC can be downloaded in source code from its -LuaForge page.

- -

History

- -
-
Version 1.0 [23/jan/2006]
-
-
Version 1.0 Beta [2/dec/2004]
-
-
Version 1.0 Alpha [10/dec/2003]
-
-
- -

LuaXMLRPC Version 1.0 follows the -package model -for Lua 5.1 (see section Installation -for more details).

- -

Credits

- -

LuaXMLRPC was designed by Roberto Ierusalimschy, André -Carregal and Tomás Guisasola as part of the -Kepler Project -which holds its copyright. It was implemented by Tomás Guisasola.

- -

LuaXMLRPC development was sponsored by -Fábrica Digital -and FINEP.

- -

Contact

- -

For more information please -contact us. -Comments are welcome!

- -
- -
- -
-

- - Valid XHTML 1.0! - -

-
- -
- - - diff --git a/doc/us/license.html b/doc/us/license.html deleted file mode 100755 index da5e75b..0000000 --- a/doc/us/license.html +++ /dev/null @@ -1,112 +0,0 @@ - - - - LuaXMLRPC: XML-RPC interface to the Lua programming language - - - - - -
- -
- -
LuaXMLRPC
-
XML-RPC interface to the Lua programming language
-
- -
- - - -
- -

License

- -

-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 Open -Source software. Its licenses are compatible with GPL. LuaXMLRPC is not in -the public domain and the -Kepler Project hold its copyright. The legal details are below. -

- -

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.

- -

The LuaXMLRPC library is designed and implemented by Roberto -Ierusalimschy, André Carregal and Tomás Guisasola. -The implementation is not derived from licensed software.

- -
-

-Copyright © 2003-2006 Kepler Project. -

-

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:

- -

The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software.

- -

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.

- -
- -
- -
-

Valid XHTML 1.0!

-
- -
- - - diff --git a/doc/us/manual.html b/doc/us/manual.html deleted file mode 100755 index 54e9970..0000000 --- a/doc/us/manual.html +++ /dev/null @@ -1,315 +0,0 @@ - - - - LuaXMLRPC: XML-RPC interface to the Lua programming language - - - - - -
- -
- -
LuaXMLRPC
-
XML-RPC interface to the Lua programming language
-
- -
- - - -
- -

Introduction

- -

LuaXMLRPC is a Lua library that can be used -to build XML-RPC clients and -servers. It enables a Lua program to:

- -
    -
  • Encode and decode XML-RPC messages without handling XML code
    • -
  • Transform Lua data structures 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.

- -

LuaXMLRPC is based on -LuaExpat and on -Lua 5.0. -The abstraction layer over HTTP depends on -LuaSocket 2.0.

- -

Installation

- -

LuaXMLRPC is composed by three Lua files:

- -
    -
  • xmlrpc.lua
    • -
  • FALTA COLOCAR OS NOMES DOS OUTROS ARQUIVOS
    • -
- -These files should be copied to a directory named xmlrpc created in your -LUA_PATH.

- -

LuaXMLRPC follows the -package model -for Lua 5.1, therefore it should be "installed". Refer to - -Compat-5.1 configuration section about how to install the module.

- -

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 data item or table, -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(s)Lua object
- double
- int
- i4 - 		number
stringstring
booleanboolean
- struct
- arrray - 		table
other elements -
{
-    tag = "element name",
-    [1] = <first child>,
-    [2] = <second child>,
-    [3] = ...,
-}
-
- - -

From Lua to XML-RPC

- -

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:

- - - - - - - - - - - - - - - - - - - - - - - - - - -
Lua objectXML-RPC data type
numberint or double
stringstring
booleanboolean
{ key = val } -
-<struct>
-  <member>
-    <name>key</name>
-    <value>val</value>
-  </member>
-</struct>
-
- val is converted according to the same rules. -
- -

Ifn case of a table that has numeric keys, the resulting struct will -have the string representation of these numbers as keys (e.g. -"1" instead of 1). The library tries to -convert integral numbers to integer types, otherwise converting -them to floating point numbers.

- -

Library functions

- -

The xmlrpc.lua file implements the functions that encode and decode XML-RPC messages and transform -data types between the Lua and XML-RPC. The functions are:

- -
-
clEncode (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.
- -
clDecode (method_response) => ok, 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 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 - false value is followed by the XMLRPC - faultString and the faultCode. This values are - extracted from the fault element.
- -
srvDecode (method_call) => method_name, list_params
-
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 methodCall 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.
- -
srvEncode (object, is_fault) => method_response
-
Build a XML-RPC document containing a methodResponse - 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 one value so a - Lua function that returns more than one value has to pack - them into a table to guarantee that all of them will be returned. - The second parameter (is_fault) can be used to force a - fault element to be generated instead of a - params. In this case, the Lua object must be a table - with the members faultCode and - faultString.
- -
srvMethods (tab_or_func)
-
Register the methods on the server. The parameter can be a table - or a dispatching function. If a table is given it can have - one level of objects with the corresponding methods. If a - function is given, it will replace the dispatcher.
- -
dispatch (method_name) => function
-
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.
-
- - -

Client side

- -

The http.lua file implements a simple -stand-alone client based on -LuaSocket 2.0. The -following function is provided:

- -
-
call (url, method [, params])
-
Execute the call to method at location - url with the given params (if any). The - method and params parameters will be just - passed to clEncode function. The result is - the same as clDecode function: 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).
-
- - -

Server side

- -

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.

- -

The tests directory contains a file named -cgi.lua, which implements an example of a simple XML-RPC -server using the package post (which parses incoming -POST data from the http server). An appropriate environment for -writing Lua functions is implemented; a new assert -function generates a XML-RPC fault in case of a false condition; a -respond function creates the correct header for the -responses. The main goal of cgi.lua is to give a -starting point for other implementations.

- - -

References

- -

Related documentation can be found at: http://www.xmlrpc.com.

- -
- -
- -
-

- - Valid XHTML 1.0! - -

-
- -
- - -