source: project/wiki/xml-rpc @ 8722

Last change on this file since 8722 was 8722, checked in by svnwiki, 12 years ago

Changes applied for Ozzi Lee (71.38.23.88) through svnwiki:

Learned to spell "Winkelmann"

File size: 5.6 KB
Line 
1[[tags: eggs]]
2
3==xml-rpc
4
5[[toc:]]
6
7=== Description
8
9A library for XML-RPC client/servers.
10
11=== Author
12
13[[felix winkelmann|Felix Winkelmann]]
14
15=== Requirements
16
17http
18ssax
19base64
20url
21
22=== Download
23
24
25[[http://www.call-with-current-continuation.org/eggs/xml-rpc.egg|xml-rpc.egg]]
26
27=== Documentation
28
29
30  [procedure] (xml-rpc:register-method NAME PROC [DOCSTRING [PATH]])
31
32Registers 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.
33See define-remote-method for a simpler method of defining XML-RPC procedures.
34
35  [procedure] (xml-rpc:method-documentation NAME [PATH])
36
37Returns the documentation-string of the method with the name NAME (a string) at the URL PATH (which defaults to "/RPC2").
38
39  [parameter] (xml-rpc:current-method-path)
40
41Contains 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.
42
43  [syntax] (define-remote-method (NAME VAR ... [. RVAR]) [DOCSTRING] BODY ...)
44
45A more convenient syntax for defining remotely callable procedures. The optional DOCSTRING can be accessed by xml-rpc:method-documentation.
46
47The following table summarizes how XML-RPC values map to Scheme data and vice versa:
48
49Scheme -> XML-RPC:
50<table>
51<tr>
52<th>exact integer</th>
53<td>i4</td>
54</tr>
55<tr>
56<th>number</th>
57<td>double</td>
58</tr>
59<tr>
60<th>boolean</th>
61<td>boolean</td>
62</tr>
63<tr>
64<th>string</th>
65<td>string</td>
66</tr>
67<tr>
68<th>byte-vector</th>
69<td>base64</td>
70</tr>
71<tr>
72<th>vector</th>
73<td>array</td>
74</tr>
75<tr>
76<th>a-list</th>
77<td>struct</td>
78</tr>
79<tr>
80<th>list</th>
81<td>struct</td>
82</tr>
83</table>
84
85XML-RPC -> Scheme
86<table>
87<tr>
88<th>i4, int, double</th>
89<td>number</td>
90</tr>
91<tr>
92<th>boolean</th>
93<td>boolean</td>
94</tr>
95<tr>
96<th>string</th>
97<td>string</td>
98</tr>
99<tr>
100<th>base64</th>
101<td>byte-vector</td>
102</tr>
103<tr>
104<th>array</th>
105<td>vector</td>
106</tr>
107<tr>
108<th>struct</th>
109<td>a-list</td>
110</tr>
111<tr>
112<th>dateTime.iso8601</th>
113<td>string</td>
114</tr>
115</table>
116
117This 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.
118
119=== Examples
120
121Fetch time from xml-rpc.org:
122
123  (define currentTime
124    (xml-rpc:server "xml-rpc.org") )
125 
126  (define getCurrentTime
127    (currentTime "currentTime.getCurrentTime") )
128 
129  (print (getCurrentTime))
130 
131A simple "hello" server:
132
133  % cat hello.scm
134  (require-extension xml-rpc-server)
135 
136  (define-remote-method (hello var)
137    (sprintf "Hello, ~A!" var) )
138 
139  ((http:make-server 4242))
140 
141  % cat client.scm
142  (require-extension xml-rpc-client)
143 
144  (define srv (xml-rpc:server "http://localhost:4242/RPC2"))
145  (define hello (srv "hello"))
146 
147  (print "-> " (hello "you"))
148 
149  % csi -script hello.scm &
150  % csi -script client.scm
151 
152  -> Hello, you!
153
154=== Changelog
155
156* 1.14 HTTPS-URLs are recognized, user, password and attributes are recognized as keyword parameters to xml-rpc:server. [Thomas Chust]
157* 1.13 Server replies with proper protocol [guess who reported it?]
158* 1.12 Fixed another bug, again reported by Daishi
159* 1.11 Fixed bugs in xml content-parser and PI matching [reported by Daishi Kato]
160* 1.10 Bug-fixes and improvements by Hans Bulfone
161* 1.9 Adapted to SRFI-69-compatible hash-tables
162* 1.8 Interpretation of HOST argument of xml-rpc:server is now consistent with documentation. [edw]
163* 1.7 XML content-parser used old signature.
164* 1.6 Fixed small bug in URL handling. [edw]
165* 1.5 Server now supports processing instructions in requests. Xml-rpc:server now accepts a URL in HOST argument. [edw@poseur.com]
166* 1.4 Adapted to new setup scheme.
167* 1.3 Reponse parsing did not accept XML processing instructions.
168* 1.2 Unmarshaling of dateTime.iso8601 results was wrong (again!).
169* 1.1 Unmarshaling of dateTime.iso8601 results was wrong.
170* 1.0
171
172=== License
173
174  Copyright (c) 2003-2006, Felix L. Winkelmann
175  All rights reserved.
176 
177  Redistribution and use in source and binary forms, with or without
178  modification, are permitted provided that the following conditions are
179  met:
180 
181    Redistributions of source code must retain the above copyright
182    notice, this list of conditions and the following disclaimer.
183 
184    Redistributions in binary form must reproduce the above copyright
185    notice, this list of conditions and the following disclaimer in the
186    documentation and/or other materials provided with the distribution.
187 
188    Neither the name of the author nor the names of its contributors may
189    be used to endorse or promote products derived from this software
190    without specific prior written permission.
191 
192  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
193  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
194  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
195  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
196  HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
197  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
198  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
199  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
200  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
201  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
202  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
203  DAMAGE.
Note: See TracBrowser for help on using the repository browser.