1XMLRPC(3) ERLANG MODULE DEFINITION XMLRPC(3)
2
6 xmlrpc - XML-RPC library
7
9 This is an HTTP 1.1 compliant XML-RPC Erlang library. It is designed to
10 make it easy to write XML-RPC Erlang clients and/or servers. The
11 library is compliant with the XML-RPC specification published by
12 http://www.xmlrpc.org/.
13
15 call(Socket, URI, Payload)
16 call(Host, Port, URI, Payload)
17 call(Socket, URI, Payload, KeepAlive, Timeout)
18 call(Host, Port, URI, Payload, KeepAlive, Timeout) -> Result
19 Types Socket = socket()
21 URI = string()
22 Payload = {call, Method, [Value]}
23 Method = atom()
24 Value = integer() | float() | string() | Boolean |
25 ISO8601Date | Base64 | Struct | Array
26 Boolean = true | false
27 ISO8601Date = {date, string()}
28 Base64 = {base64, string()}
29 Struct = {struct, [{Key, Value}]}
30 Key = atom()
31 Array = {array, [Value]}
32 Host = string() | ip()
33 Port = integer()
34 KeepAlive = true | false
35 Timeout = integer()
36 ResponsePayload = {response, [Value]} | {response, Fault}
37 Fault = {fault, FaultCode, FaultString}
38 FaultCode = integer()
39 FaultString = string()
40 Result = {ok, ResponsePayload} | {error, Reason} | {ok,
41 Socket, ResponsePayload} | {error, Socket, Reason}
42 Reason = term()
43 Calls an XML-RPC server listening on Host:Port. The URI and Pay‐
45 load is used in the HTTP POST request being sent to the server.
46 The Value is converted to XML (see DATA TYPES below) and is used
47 as request body.
48 If KeepAlive is true a Socket is returned. The socket can be
50 used to send several calls on the same connection in accordance
51 with HTTP 1.1. If no server response is received within Timeout
52 milli-seconds {error, timeout} or {error, Socket, timeout} is
53 returned.
54 KeepAlive and Timeout default to false and 60000 milli-seconds.
56 See EXAMPLES section below.
58 start_link(Handler)
60 start_link(Port, MaxSessions, Timeout, Handler, State)
61 start_link(IP, Port, MaxSessions, Timeout, Handler, State) -> Result
62 Types Handler = {Module, Function}
64 Module = Function = atom()
65 Port = MaxSessions = integer()
66 Timeout = integer()
67 State = term()
68 IP = ip()
69 Result = {ok, Pid} | {error, Reason}
70 Pid = pid()
71 Reason = term()
72 Starts an XML-RPC server listening on IP:Port. If no IP address
74 is given the server listens on Port for all available IP
75 addresses. MaxSessions is used to restrict the number of concur‐
76 rent connections. If MaxSessions is reached the server accepts
77 no new connections for 5 seconds, i.e. blocking new connect
78 attempts.
79 Handler is a callback, implemented by Module:Function/2, which
81 is used to instantiate an XML-RPC server. The Timeout value is
82 used if the handler is keepalive oriented. State is the initial
83 state given to Module:Function/2. The resulting Pid can be used
84 as input to xmlrpc:stop/1.
85 See Module:Function/2 and EXAMPLES below.
87 stop(Pid) -> Result
89 Types Pid = pid()
91 Result = void()
92 Stops a running XML-RPC server.
94 Module:Function(State, Payload) -> Result
96 Types State = term()
98 Payload = <See above>
99 Result = {KeepAlive, ResponsePayload} | {KeepAlive,
100 State, Timeout, ResponsePayload}
101 KeepAlive = true | false
102 ResponsePayload = <See above>
103 Timeout = integer()
104 It is up to you to implement Function clauses in Module to
106 instantiate an XML-RPC server. Every time an XML-RPC call
107 arrives the Value in the Payload gets converted to Erlang format
108 and is passed on to Module:Function/2.
109 A Function clause is supposed to return either a 2-tuple or a
111 4-tuple. KeepAlive must be false in a 2-tuple and true in a
112 4-tuple. KeepAlive decides if the connection to the client
113 should be kept open or not, i.e. compare with the KeepAlive
114 argument to call/{3,4,5,6} above.
115 State can be used as a state variable by the callback function
117 and changes made to it is propagated to the next call to Mod‐
118 ule:Function/2. The state variable is only meaningful if both
119 the client and the server is keepalive oriented. The Timeout
120 specified in start_link/{1,5,6} can be updated in the returning
121 4-tuple.
122 If KeepAlive is true and no call arrives within Timeout milli-
124 seconds the socket is closed. The socket may be closed by the
125 client before the specified timeout.
126 See EXAMPLES below.
128
130 The conversion of Value in Payload and ResponsePayload (see above) is
131 done as follows:
132 XML-RPC data type Erlang data type
134 ----------------- ----------------
135 <int> integer()
136 <boolean> true or false
137 <string> string()
138 <double> float()
139 <dateTime.iso8601> {date, string()}
140 <struct> {struct, [{Key, Value}]}
141 <array> {array, [Value]}
142 <base64> {base64, string()}
143 Read more about the XML-RPC data types in the XML-RPC specification
145 published by http://www.xmlrpc.org/.
146 Here are some examples on how Erlang format is converted to XML:
148 42 <int>42</int>
150 true <boolean>true</boolean>
152 "Kilroy was here"
154 <string>Kilroy was here</string>
155 42.5 <double>42.5</double>
157 {date, "19980717T14:08:55"}
159 <dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>
160 {struct, [{foo, 42}, {bar, 4711}]}
162 <struct>
163 <member>
164 <name>foo</name><value><int>42</int></value>
165 </member>
166 <member>
167 <name>bar</name><value><int>4711</int></value>
168 </member>
169 </struct>
170 {array, [42, 42.5}
172 <array>
173 <data>
174 <value><int>42</i4></value>
175 <value><double>42.5</double></value>
176 </data>
177 </array>
178 {date, "19980717T14:08:55"}
180 <dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>
181
183 You are strongly advised to inspect the example code in the examples/
184 directory.
185 The first example (fib_server.erl) calculates Fibonacci values and is a
187 non-keepalive server. The second example (echo_server.erl) echoes back
188 any incoming parameters and is a non-keepalive server. The third exam‐
189 ple (date_server.erl) calculates calendar values for given dates and is
190 a keepalive server which uses the state variable to provide login state
191 and different timeout settings. The fourth example (validator.erl) is a
192 validation server which can be used to validate the library using the
193 http://validator.xmlrpc.org/ service.
194 A snippet from the Fibonacci callback module in the examples/ direc‐
196 tory:
197 handler(_State, {call, fib, [N]}) when integer(N) ->
199 {false, {response, [fib(N)]}};
200 handler(_State, Payload) ->
201 FaultString = lists:flatten(io_lib:format("Unknown call: ~p", [Payload])),
202 {false, {response, {fault, -1, FaultString}}}.
203 fib(0) -> 1;
205 fib(1) -> 1;
206 fib(N) -> fib(N-1)+fib(N-2).
207 and how it can be called:
209 1> xmlrpc:call({127, 0, 0, 1}, 4567, "/", {call, fib, [0]}).
211 {ok,{response,[1]}}
212 2> xmlrpc:call({127, 0, 0, 1}, 4567, "/", {call, fib, [4]}).
213 {ok,{response,[5]}}
214 Again: You are strongly advised to inspect the example code in the
216 examples/ directory.
217
219 http://www.xmlrpc.org/
220 Home for the XML-RPC specification.
221 README Main README file for the library.
223 examples/
225 Example code
226
228 Joakim Grebeno - jocke@gleipnir.com
229jocke@gleipnir.com Jan 2003 XMLRPC(3)