XML-RPC Library

_XML-RPC_ Library
==============

By Matt Jadud and Noel Welsh
An Untyped Production

Time-stamp: <06/01/04 15:34:39 nhw>

Keywords: _xml_, _xmlrpc_, _xml-rpc_


Introduction
============

This library implements the XML-RPC protocol as specified at
http://www.xmlrpc.com/spec

XML-RPC is a popular protocol for interface to Internet
services such as blog engines.

Basic Types
===========

> struct (exn:xmlrpc exn) : ()

A subtype of exn, this exception is raised whenever the
XML-RPC library encounters an error.

> struct (exn:xmlrpc exn) : code
  
A subtype of exn:xmlrpc, this exception is raised when the
XML-RPC server responds to the client with a fault.  The
code is an integer containing the fault code returned by the
server.  The fault message returned by the server is
contained in the exception message (which is a field in the
exn type).


Client-side Functions
=====================

To use the library, require xmlrpc.ss 

> xmlrpc-server : string integer string -> (string -> (any ... -> any))
> xmlrpc-server : url -> (string -> (any ... -> any))

Returns a function configured to make XML-RPC requests to
the given URL.  The function accepts a string, the name of
the method, and returns a function of any arguments which
calls the method with the given arguments.

Example:

This example calls the examples.getStateName method on the
server betty.userland.com

  > (define betty (xmlrpc-server "betty.userland.com" 80 "RPC2"))
  > (define get-state-name (betty "examples.getStateName"))
  > (get-state-name 42)
  "Tennessee"

PLT Servlet Functions
=====================

To use the library, require xmlrpc-servlet.ss 

> add-handler : symbol (any ... -> any) -> void

An XML-RPC servlet defines one or more endpoints that 
can be invoked by a remote client. The simple act of 
defining a Scheme function does not automatically
provide it to the outside world; this would be fundamentally
unsafe. Each function to be exposed externally must be
mappend onto a name by which it can be called.

For example:

(define (add x y) (+ x y))
(add-handler 'math.add add)

These two lines of code define a Scheme function ('add') 
and provide it to an outside client under the name
'math.add'. The same function can be provided under
multiple names:

(define (add x y) (+ x y))
(add-handler 'math.add add)
(add-handler 'addFun add)

'case-lambda', 'match-lambda', and functions of 
variable argument can be bound in the same way.

> handle-xmlrpc-requests : syntax

The last form you must have in an XML-RPC servlet
is the 'handle-xmlrpc-requests' form. This expands
into a signed unit that takes each incoming request
and handles it as an XML-RPC request.

A complete XML-RPC handler for adding
two numbers would look like:

--------
(require (lib "xmlrpc-servlet.ss" "xmlrpc"))

(define (add x y) (+ x y))

(add-handler 'math.add add)

(handle-xmlrpc-requests)
--------

SERVER-SIDE WARNING
===================
As of this release, the server-side of the XML-RPC
library has not been thoroughly tested. In particular,
the server-side should be considered a "spike",
as it has not been thoroughly unit tested.

Furthermore, we have only tested the server component
against a small number of clients. Clients known to work
include:

* The Untyped XML-RPC client (Scheme)
* The Python native XML-RPC client (Python)
* Ecto, a popular blogging package for OSX (Cocoa)

These tests, however, were not exhaustive. Your milage
may vary. Please report any difficulties or patches to
jadudm at gmail dot com.

ADDITIONAL SERVER-SIDE WARNING
==============================
It appears that either the webserver, XML-RPC library, or 
some code the library depends on does not free resources
the way we'd expect. This is being actively explored, but
does imply that the library is not yet suitable for heavy,
continuous use. Once we understand where this odd behavior
is coming from, a new release will be made that addresses
this problem and declare the server-side code suitable for 
"life in the wild".