source: project/wiki/eggref/3/xml-rpc @ 14943

Last change on this file since 14943 was 14943, checked in by sjamaan, 11 years ago

Add note about 1.16 release

File size: 6.7 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==== Client
30
31Usage:
32  (require-extension xml-rpc-client)
33
34<procedure>(xml-rpc:server HOST [PORT [PATH]] [user: USER] [password: PASSWORD] [attributes: ATTRIBUTES])</procedure>
35
36Returns a procedure that, when called with the name of a remote
37XML-RPC method, will return a procedure that passes its arguments
38to the XML-RPC server which is given in {{HOST}} (a string), {{PORT}}
39(which defaults to 80) and {{PATH}} (which defaults to {{"/RPC2"}}).
40The {{USER}} and {{PASSWORD}} keyword arguments, if given, are used
41to perform basic authentication to the server. The {{ATTRIBUTES}}
42argument specifies an a-list of attributes to add to the HTTP request
43object sent to the server. If and only if {{HOST}} is a
44properly-formatted URL using the "http" or "https" schemes, the {{PORT}},
45{{PATH}}, {{USER}} and {{PASSWORD}} information found in the URL takes
46precedence over the arguments with the same meaning.
47
48==== Server
49
50Usage:
51  (require-extension xml-rpc-server)
52<procedure>(xml-rpc:register-method NAME PROC [DOCSTRING [PATH]])</procedure>
53
54Registers a remotely callable procedure {{PROC}} under {{NAME}}, which should be
55a string or a symbol. XML-RPC clients can now call this procedure (provided a HTTP
56server is started).
57
58Unhandled exceptions are returned as "fault" responses. {{PATH}} specifies the URL
59under which the remote procedure is available and defaults to {{"/RPC2"}}.
60{{DOCSTRING}} specifies an optional documentation string. See {{define-remote-method}}
61for a simpler method of defining XML-RPC procedures.
62
63<procedure>(xml-rpc:method-documentation NAME [PATH])</procedure>
64
65Returns the documentation-string of the method with the name NAME (a string) at the URL PATH (which defaults to "/RPC2").
66
67<parameter>(xml-rpc:current-method-path)</parameter>
68
69Contains 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.
70
71<macro>(define-remote-method (NAME VAR ... [. RVAR]) [DOCSTRING] BODY ...)</macro>
72
73A more convenient syntax for defining remotely callable procedures. The optional DOCSTRING can be accessed by xml-rpc:method-documentation.
74
75==== Type conversion
76
77The following table summarizes how XML-RPC values map to Scheme data and vice versa:
78
79Scheme -> XML-RPC:
80<table>
81<tr>
82<th>exact integer</th>
83<td>i4</td>
84</tr>
85<tr>
86<th>number</th>
87<td>double</td>
88</tr>
89<tr>
90<th>boolean</th>
91<td>boolean</td>
92</tr>
93<tr>
94<th>string</th>
95<td>string</td>
96</tr>
97<tr>
98<th>byte-vector</th>
99<td>base64</td>
100</tr>
101<tr>
102<th>vector</th>
103<td>array</td>
104</tr>
105<tr>
106<th>a-list</th>
107<td>struct</td>
108</tr>
109<tr>
110<th>list</th>
111<td>struct</td>
112</tr>
113</table>
114
115XML-RPC -> Scheme
116<table>
117<tr>
118<th>i4, int, double</th>
119<td>number</td>
120</tr>
121<tr>
122<th>boolean</th>
123<td>boolean</td>
124</tr>
125<tr>
126<th>string</th>
127<td>string</td>
128</tr>
129<tr>
130<th>base64</th>
131<td>byte-vector</td>
132</tr>
133<tr>
134<th>array</th>
135<td>vector</td>
136</tr>
137<tr>
138<th>struct</th>
139<td>a-list</td>
140</tr>
141<tr>
142<th>dateTime.iso8601</th>
143<td>string</td>
144</tr>
145</table>
146
147This 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.
148
149=== Examples
150
151Fetch time from xml-rpc.org:
152
153  (require-extension xml-rpc-client)
154
155  (define currentTime
156    (xml-rpc:server "xml-rpc.org") )
157 
158  (define getCurrentTime
159    (currentTime "currentTime.getCurrentTime") )
160 
161  (print (getCurrentTime))
162 
163A simple "hello" server:
164
165  % cat hello.scm
166  (require-extension xml-rpc-server)
167 
168  (define-remote-method (hello var)
169    (sprintf "Hello, ~A!" var) )
170 
171  ((http:make-server 4242))
172 
173  % cat client.scm
174  (require-extension xml-rpc-client)
175 
176  (define srv (xml-rpc:server "http://localhost:4242/RPC2"))
177  (define hello (srv "hello"))
178 
179  (print "-> " (hello "you"))
180 
181  % csi -script hello.scm &
182  % csi -script client.scm
183 
184  -> Hello, you!
185
186=== Changelog
187
188* 1.16 Allow empty strings (quick hack) [Peter Bex]
189* 1.14 HTTPS-URLs are recognized, user, password and attributes are recognized as keyword parameters to xml-rpc:server. [Thomas Chust]
190* 1.13 Server replies with proper protocol [guess who reported it?]
191* 1.12 Fixed another bug, again reported by Daishi
192* 1.11 Fixed bugs in xml content-parser and PI matching [reported by Daishi Kato]
193* 1.10 Bug-fixes and improvements by Hans Bulfone
194* 1.9 Adapted to SRFI-69-compatible hash-tables
195* 1.8 Interpretation of HOST argument of xml-rpc:server is now consistent with documentation. [edw]
196* 1.7 XML content-parser used old signature.
197* 1.6 Fixed small bug in URL handling. [edw]
198* 1.5 Server now supports processing instructions in requests. Xml-rpc:server now accepts a URL in HOST argument. [edw@poseur.com]
199* 1.4 Adapted to new setup scheme.
200* 1.3 Reponse parsing did not accept XML processing instructions.
201* 1.2 Unmarshaling of dateTime.iso8601 results was wrong (again!).
202* 1.1 Unmarshaling of dateTime.iso8601 results was wrong.
203* 1.0
204
205=== License
206
207  Copyright (c) 2003-2006, Felix L. Winkelmann
208  All rights reserved.
209 
210  Redistribution and use in source and binary forms, with or without
211  modification, are permitted provided that the following conditions are
212  met:
213 
214    Redistributions of source code must retain the above copyright
215    notice, this list of conditions and the following disclaimer.
216 
217    Redistributions in binary form must reproduce the above copyright
218    notice, this list of conditions and the following disclaimer in the
219    documentation and/or other materials provided with the distribution.
220 
221    Neither the name of the author nor the names of its contributors may
222    be used to endorse or promote products derived from this software
223    without specific prior written permission.
224 
225  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
226  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
227  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
228  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
229  HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
230  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
231  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
232  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
233  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
234  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
235  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
236  DAMAGE.
Note: See TracBrowser for help on using the repository browser.