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

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

Document the client (apparently this got omitted somehow)

File size: 6.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==== 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.14 HTTPS-URLs are recognized, user, password and attributes are recognized as keyword parameters to xml-rpc:server. [Thomas Chust]
189* 1.13 Server replies with proper protocol [guess who reported it?]
190* 1.12 Fixed another bug, again reported by Daishi
191* 1.11 Fixed bugs in xml content-parser and PI matching [reported by Daishi Kato]
192* 1.10 Bug-fixes and improvements by Hans Bulfone
193* 1.9 Adapted to SRFI-69-compatible hash-tables
194* 1.8 Interpretation of HOST argument of xml-rpc:server is now consistent with documentation. [edw]
195* 1.7 XML content-parser used old signature.
196* 1.6 Fixed small bug in URL handling. [edw]
197* 1.5 Server now supports processing instructions in requests. Xml-rpc:server now accepts a URL in HOST argument. [edw@poseur.com]
198* 1.4 Adapted to new setup scheme.
199* 1.3 Reponse parsing did not accept XML processing instructions.
200* 1.2 Unmarshaling of dateTime.iso8601 results was wrong (again!).
201* 1.1 Unmarshaling of dateTime.iso8601 results was wrong.
202* 1.0
203
204=== License
205
206  Copyright (c) 2003-2006, Felix L. Winkelmann
207  All rights reserved.
208 
209  Redistribution and use in source and binary forms, with or without
210  modification, are permitted provided that the following conditions are
211  met:
212 
213    Redistributions of source code must retain the above copyright
214    notice, this list of conditions and the following disclaimer.
215 
216    Redistributions in binary form must reproduce the above copyright
217    notice, this list of conditions and the following disclaimer in the
218    documentation and/or other materials provided with the distribution.
219 
220    Neither the name of the author nor the names of its contributors may
221    be used to endorse or promote products derived from this software
222    without specific prior written permission.
223 
224  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
225  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
226  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
227  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
228  HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
229  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
230  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
231  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
232  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
233  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
234  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
235  DAMAGE.
Note: See TracBrowser for help on using the repository browser.