Common Lisp Package: CXML-RPC

README:

CXML-RPC: An xml-rpc library for Common Lisp

This library implements xml-rpc client and server functionality using Drakma, CXML and Hunchentoot.

Installation

Get it via git:

git clone http://github.com/antifuchs/cxml-rpc 

Then adjust your ASDF to find cxml-rpc.asd. After that,

(asdf:oos 'asdf:load-op :cxml-rpc) 

Usage

An XML-RPC Client

Acting as an XML-RPC client is pretty easy: Just call the functions on the endpoints you need. The function's first return value is the value returned by the server, and the second return value is its type.

* (xrpc:call "http://betty.userland.com/RPC2" "examples.getStateName" '(:integer 41))  
"South Dakota"  
:STRING 
Argument passing

Since the mapping of CL types to XML-RPC types is not easily DWIM-able, you need to pass args with explicit type hints. CXML-RPC maps these types (as keywords):

  • :boolean - generalized boolean
  • :integer - 4-octet integers
  • :double - floating-point doubles
  • :string - strings
  • :time - universal times as CL integers
  • :base64 - strings, file streams or vectors containing (unsigned-byte 8) elements.
  • :struct - alists
  • :array - sequences

An XML-RPC Server

You can run multiple XML RPC handlers in your hunchentoot instance: These are identified by a handler tag that you can choose. This tag is not exposed to the outside world, so you can run multiple sites (or endpoints) with a different set of xml-rpc methods in the same lisp image.

Step one: Teach hunchentoot about your handler.

(push  
     (hunchentoot:create-prefix-dispatcher "/RPC2"  
                                           (cxml:cxml-rpc-method-handler 'some-tag))  
     hunchentoot:*dispatch-table*) 

This tells hunchentoot to dispatch xml-rpc calls on /RPC2 to dispatch xml-rpc methods. This handler will serve only methods that are defined with the group tag some-tag.

Step two: Define methods.

Define-xrpc-method is what you use to create a function that can be called from xml-rpc. Its arguments are:

  1. The function name and handler group (following the example above, that should be some-tag),
  2. a list of argument variables,
  3. a type signature: First the return type, then the parameter types,
  4. an optional docstring.

CXML-RPC allows introspection via the system.getCapabilities, system.listMethods, system.methodHelp, and system.methodSignature.

(define-xrpc-method (add some-tag) (a b) (:integer :integer :integer)  
  "Add two numbers"  
  (+ a b)) 

FUNCTION

Public

Undocumented

CALL (URI FUNCTION PARAMETERS &REST DRAKMA-ARGS)

CALL-WITH-ENCODER (URI ENCODER DECODER &REST DRAKMA-ARGS &KEY PROTOCOL COOKIE-JAR BASIC-AUTHORIZATION USER-AGENT PROXY PROXY-BASIC-AUTHENTICATION ADDITIONAL-HEADERS REDIRECT READ-TIMEOUT WRITE-TIMEOUT CONNECT-TIMEOUT)

CXML-RPC-METHOD-HANDLER (TAG)

DECODE-TIME (STRING)

ENCODE-TIME (UTIME)

ENCODED-REQUEST (FUNCTION-NAME &REST ARGS)

ENCODER (FUNCTION-NAME &REST ARGS)

ENSURE-XRPC-METHOD (HANDLER-TAG NAME SIGNATURE DOCUMENTATION FUNCTION)

INVOKE-METHOD (METHOD-NAME PARAM-TYPES PARAMS &KEY (OCTETP T) ((TAG *CURRENT-TAG*) *CURRENT-TAG*))

LOOKUP-METHOD (HANDLER-TAG METHOD-NAME)

LOOKUP-METHOD-SIGNATURE (HANDLER-TAG METHOD-NAME &KEY FIXUP-P)

TRACE-XML-RESPONSE (OUTPUT-STREAM URI FUNCTION PARAMETERS &REST DRAKMA-ARGS)

Private

SYSTEM-CAPABILITIES

Returns a structural representation of the capabilities that this xml-rpc implementation supports.

SYSTEM-LIST-METHODS

Lists the methods that are defined on this server.

SYSTEM-METHOD-HELP (METHOD-NAME)

Returns a method's documentation as an XML-RPC string.

SYSTEM-METHOD-SIGNATURE (METHOD-NAME)

Returns an array of method signatures (arrays of strings listing first the return type, then the argument types).

Undocumented

CHARACTER-STREAM-P (STREAM)

CHECK-METHOD-SIGNATURE-FOR-INVOCATION (PARAM-TYPES SIGNATURE/RETURN &AUX (SIGNATURE (CDR SIGNATURE/RETURN)))

DECODE-METHOD-CALL (STREAM)

DECODE-METHOD-NAME (SOURCE)

DECODE-NAME (SOURCE)

DECODE-PARAMETER (SOURCE)

DECODE-RESPONSE (STREAM)

DECODE-VALUE (SOURCE)

DWIM-TYPE-FOR (OBJECT)

ENCODE-PARAM (TYPE OBJECT)

ENCODE-RESPONSE (OCTETP FAULTP OBJECT &OPTIONAL (TYPE (DWIM-TYPE-FOR OBJECT)))

ENCODE-VALUE (TYPE OBJECT)

FIRST-INVALID-INTEGER-POSITION (STRING)

FIX-METHOD-SIGNATURE (SIGNATURE)

INVOKE-EXPECTING-ELEMENT/CHARACTERS (SOURCE ELEMENT CONTINUATION)

INVOKE-EXPECTING-ELEMENT/CONSUMING (SOURCE ELEMENT CONTINUATION)

REPORT-ERROR (FAULT-CODE FAULT-TEXT)

SIGNATURE-ARG-COUNT (SIGNATURE)

SKIP* (SOURCE &REST ARGS)

SKIP-CHARACTERS (SOURCE)

TYPE-TAG-FOR (TAG)

UNIVERSAL-TIME-TO-XML-RPC-TIME-STRING (UTIME)

XMLRPC-TYPE-TAG (LISP-TAG)

MACRO

Public

Undocumented

DEFINE-XRPC-METHOD ((NAME HANDLER-TAG) (&REST ARGS) (&REST SIGNATURE) &BODY OPTIONAL-DOCSTRING-AND-BODY)

Private

Undocumented

DO-TAGGED-SEQUENCE ((TYPE VALUE LIST) &BODY BODY)

EXPECTING-ELEMENT/CHARACTERS ((SOURCE LNAME CHARACTER-VAR) &BODY BODY)

EXPECTING-ELEMENT/CONSUMING ((SOURCE LNAME) &BODY BODY)

GENERIC-FUNCTION

Public

Undocumented

EXPECTED-ELEMENT (CONDITION)

SETFEXPECTED-ELEMENT (NEW-VALUE CONDITION)

FAULT-CODE-OF (CONDITION)

SETFFAULT-CODE-OF (NEW-VALUE CONDITION)

FAULT-PHRASE-OF (CONDITION)

SETFFAULT-PHRASE-OF (NEW-VALUE CONDITION)

FAULTY-ELEMENT (CONDITION)

SETFFAULTY-ELEMENT (NEW-VALUE CONDITION)

HEADERS-OF (CONDITION)

SETFHEADERS-OF (NEW-VALUE CONDITION)

MALFORMED-CONTENT (CONDITION)

SETFMALFORMED-CONTENT (NEW-VALUE CONDITION)

REASON-OF (CONDITION)

SETFREASON-OF (NEW-VALUE CONDITION)

STATUS-CODE-OF (CONDITION)

SETFSTATUS-CODE-OF (NEW-VALUE CONDITION)

TYPE-OF-MALFORMED-CONTENT (CONDITION)

SETFTYPE-OF-MALFORMED-CONTENT (NEW-VALUE CONDITION)

Private

Undocumented

DECODE-OBJECT (TYPE SOURCE)

ENCODE-OBJECT (TYPE OBJECT)

EXPECTED-ARG (CONDITION)

SETFEXPECTED-ARG (NEW-VALUE CONDITION)

GOT-ARG (CONDITION)

SETFGOT-ARG (NEW-VALUE CONDITION)

GOT-ARGS (CONDITION)

SETFGOT-ARGS (NEW-VALUE CONDITION)

MAXIMUM (CONDITION)

SETFMAXIMUM (NEW-VALUE CONDITION)

MINIMUM (CONDITION)

SETFMINIMUM (NEW-VALUE CONDITION)

NAME-OF (CONDITION)

SETFNAME-OF (NEW-VALUE CONDITION)

POSITION-OF (CONDITION)

SETFPOSITION-OF (NEW-VALUE CONDITION)

TAG-OF (CONDITION)

SETFTAG-OF (NEW-VALUE CONDITION)

TYPE-ALIST (CONDITION)

SETFTYPE-ALIST (NEW-VALUE CONDITION)

SLOT-ACCESSOR

Private

Undocumented

ISO8601-OF (OBJECT)

SETFISO8601-OF (NEW-VALUE OBJECT)

UNIVERSAL-TIME-OF (OBJECT)

SETFUNIVERSAL-TIME-OF (NEW-VALUE OBJECT)

VARIABLE

Private

*PRINT-TIMESTAMPS-IN-UTC-P*

Specifies whether so-called iso8601 timestamps are printed in the local time zone (as mandated by the xml-rpc specification) or as UTC, which will probably break clients and servers.

*USER-DEFINED-METHOD-SIGNATURES*

Method signatures stored under the key (handler-tag . "method-name").

*USER-DEFINED-METHODS*

Methods stored under the key (handler-tag . "method-name").

Undocumented

*SYSTEM-METHODS*

*XML-RPC-TYPE-ALIST*

CLASS

Private

Undocumented

XML-RPC-DATE

CONDITION

Public

Undocumented

BAD-RESPONSE-STRUCTURE

CXML-RPC-CONDITION

CXML-RPC-FAULT

HTTP-ERROR

MALFORMED-VALUE-CONTENT

NETWORK-ERROR

Private

Undocumented

BAD-TYPE-SPECIFIER

METHOD-ARG-COUNT-MISMATCH

METHOD-ARG-TYPE-MISMATCH

METHOD-NOT-FOUND