xml-rpc

  1. xml-rpc
    1. Description
    2. Author
    3. Requirements
    4. Download
    5. Documentation
      1. Client
      2. Server
      3. Type conversion
    6. Examples
    7. Changelog
    8. License

Description

A library for XML-RPC client/servers.

Author

Felix Winkelmann

Requirements

http ssax base64 url

Download

xml-rpc.egg

Documentation

Client

Usage:

 (require-extension xml-rpc-client)
[procedure] (xml-rpc:server HOST [PORT [PATH]] [user: USER] [password: PASSWORD] [attributes: ATTRIBUTES])

Returns a procedure that, when called with the name of a remote XML-RPC method, will return a procedure that passes its arguments to the XML-RPC server which is given in HOST (a string), PORT (which defaults to 80) and PATH (which defaults to "/RPC2"). The USER and PASSWORD keyword arguments, if given, are used to perform basic authentication to the server. The ATTRIBUTES argument specifies an a-list of attributes to add to the HTTP request object sent to the server. If and only if HOST is a properly-formatted URL using the "http" or "https" schemes, the PORT, PATH, USER and PASSWORD information found in the URL takes precedence over the arguments with the same meaning.

Server

Usage:

 (require-extension xml-rpc-server)
[procedure] (xml-rpc:register-method NAME PROC [DOCSTRING [PATH]])

Registers a remotely callable procedure PROC under NAME, which should be a string or a symbol. XML-RPC clients can now call this procedure (provided a HTTP server is started).

Unhandled exceptions are returned as "fault" responses. PATH specifies the URL under which the remote procedure is available and defaults to "/RPC2". DOCSTRING specifies an optional documentation string. See define-remote-method for a simpler method of defining XML-RPC procedures.

[procedure] (xml-rpc:method-documentation NAME [PATH])

Returns the documentation-string of the method with the name NAME (a string) at the URL PATH (which defaults to "/RPC2").

[parameter] (xml-rpc:current-method-path)

Contains the URL (a string) under which the currently executing method is called. Outside of the dynamic context of an XML-RPC method invocation, the value of this parameter is unspecified.

[syntax] (define-remote-method (NAME VAR ... [. RVAR]) [DOCSTRING] BODY ...)

A more convenient syntax for defining remotely callable procedures. The optional DOCSTRING can be accessed by xml-rpc:method-documentation.

Type conversion

The following table summarizes how XML-RPC values map to Scheme data and vice versa:

Scheme -> XML-RPC:

exact integer i4
number double
boolean boolean
string string
byte-vector base64
vector array
a-list struct
list struct

XML-RPC -> Scheme

i4, int, double number
boolean boolean
string string
base64 byte-vector
array vector
struct a-list
dateTime.iso8601 string

This implementation of XML-RPC is extended to allow returning multiple values. Errors during the execution of a server-method are propagated to the client as "fault" responses.

Examples

Fetch time from xml-rpc.org:

 (require-extension xml-rpc-client)
 (define currentTime
   (xml-rpc:server "xml-rpc.org") )
 
 (define getCurrentTime
   (currentTime "currentTime.getCurrentTime") )
 
 (print (getCurrentTime))
 

A simple "hello" server:

 % cat hello.scm
 (require-extension xml-rpc-server)
 
 (define-remote-method (hello var)
   (sprintf "Hello, ~A!" var) )
 
 ((http:make-server 4242))
 
 % cat client.scm
 (require-extension xml-rpc-client)
 
 (define srv (xml-rpc:server "http://localhost:4242/RPC2"))
 (define hello (srv "hello"))
 
 (print "-> " (hello "you"))
 
 % csi -script hello.scm &
 % csi -script client.scm
 
 -> Hello, you!

Changelog

License

 Copyright (c) 2003-2006, Felix L. Winkelmann
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
   Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 
   Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
 
   Neither the name of the author nor the names of its contributors may
   be used to endorse or promote products derived from this software
   without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 DAMAGE.