Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documentation added

  • Loading branch information...
commit a7fd3310d8e1fe3e4c27736bfae934f0865f30b9 1 parent 5b814e2
Ralf Weinbrecher authored
Showing with 253 additions and 0 deletions.
  1. +253 −0 doc/xmlrpc.txt
253 doc/xmlrpc.txt
View
@@ -0,0 +1,253 @@
+XMLRPC(3) ERLANG MODULE DEFINITION XMLRPC(3)
+
+
+
+MODULE
+ xmlrpc - XML-RPC library
+
+DESCRIPTION
+ This is an HTTP 1.1 compliant XML-RPC Erlang library. It
+ is designed to make it easy to write XML-RPC Erlang
+ clients and/or servers. The library is compliant with the
+ XML-RPC specification published by http://www.xmlrpc.org/.
+
+EXPORTS
+ call(Socket, URI, Payload)
+ call(Host, Port, URI, Payload)
+ call(Socket, URI, Payload, KeepAlive, Timeout)
+ call(Host, Port, URI, Payload, KeepAlive, Timeout) ->
+ Result
+
+ Types Socket = socket()
+ URI = string()
+ Payload = {call, Method, [Value]}
+ Method = atom()
+ Value = integer() | float() | string() |
+ Boolean | ISO8601Date | Base64 | Struct |
+ Array
+ Boolean = true | false
+ ISO8601Date = {date, string()}
+ Base64 = {base64, string()}
+ Struct = {struct, [{Key, Value}]}
+ Key = atom()
+ Array = {array, [Value]}
+ Host = string() | ip()
+ Port = integer()
+ KeepAlive = true | false
+ Timeout = integer()
+ ResponsePayload = {response, [Value]} |
+ {response, Fault}
+ Fault = {fault, FaultCode, FaultString}
+ FaultCode = integer()
+ FaultString = string()
+ Result = {ok, ResponsePayload} | {error,
+ Reason} | {ok, Socket, ResponsePayload} |
+ {error, Socket, Reason}
+ Reason = term()
+
+ Calls an XML-RPC server listening on Host:Port. The
+ URI and Payload is used in the HTTP POST request
+ being sent to the server. The Value is converted to
+ XML (see DATA TYPES below) and is used as request
+ body.
+
+ If KeepAlive is true a Socket is returned. The
+ socket can be used to send several calls on the
+ same connection in accordance with HTTP 1.1. If no
+ server response is received within Timeout milli-
+ seconds {error, timeout} or {error, Socket, time-
+ out} is returned.
+
+ KeepAlive and Timeout default to false and 60000
+ milli-seconds.
+
+ See EXAMPLES section below.
+
+ start_link(Handler)
+ start_link(Port, MaxSessions, Timeout, Handler, State)
+ start_link(IP, Port, MaxSessions, Timeout, Handler, State)
+ -> Result
+
+ Types Handler = {Module, Function}
+ Module = Function = atom()
+ Port = MaxSessions = integer()
+ Timeout = integer()
+ State = term()
+ IP = ip()
+ Result = {ok, Pid} | {error, Reason}
+ Pid = pid()
+ Reason = term()
+
+ Starts an XML-RPC server listening on IP:Port. If
+ no IP address is given the server listens on Port
+ for all available IP addresses. MaxSessions is used
+ to restrict the number of concurrent connections.
+ If MaxSessions is reached the server accepts no new
+ connections for 5 seconds, i.e. blocking new con-
+ nect attempts.
+
+ Handler is a callback, implemented by Module:Func-
+ tion/2, which is used to instantiate an XML-RPC
+ server. The Timeout value is used if the handler is
+ keepalive oriented. State is the initial state
+ given to Module:Function/2. The resulting Pid can
+ be used as input to xmlrpc:stop/1.
+
+ See Module:Function/2 and EXAMPLES below.
+
+ stop(Pid) -> Result
+
+ Types Pid = pid()
+ Result = void()
+
+ Stops a running XML-RPC server.
+
+ Module:Function(State, Payload) -> Result
+
+ Types State = term()
+ Payload = <See above>
+ Result = {KeepAlive, ResponsePayload} |
+ {KeepAlive, State, Timeout, ResponsePayload}
+ KeepAlive = true | false
+ ResponsePayload = <See above>
+ Timeout = integer()
+
+ It is up to you to implement Function clauses in
+ Module to instantiate an XML-RPC server. Every time
+ an XML-RPC call arrives the Value in the Payload
+ gets converted to Erlang format and is passed on to
+ Module:Function/2.
+
+ A Function clause is supposed to return either a
+ 2-tuple or a 4-tuple. KeepAlive must be false in a
+ 2-tuple and true in a 4-tuple. KeepAlive decides if
+ the connection to the client should be kept open or
+ not, i.e. compare with the KeepAlive argument to
+ call/{3,4,5,6} above.
+
+ State can be used as a state variable by the call-
+ back function and changes made to it is propagated
+ to the next call to Module:Function/2. The state
+ variable is only meaningful if both the client and
+ the server is keepalive oriented. The Timeout
+ specified in start_link/{1,5,6} can be updated in
+ the returning 4-tuple.
+
+ If KeepAlive is true and no call arrives within
+ Timeout milli-seconds the socket is closed. The
+ socket may be closed by the client before the spec-
+ ified timeout.
+
+ See EXAMPLES below.
+
+DATA TYPES
+ The conversion of Value in Payload and ResponsePayload
+ (see above) is done as follows:
+
+ XML-RPC data type Erlang data type
+ ----------------- ----------------
+ <int> integer()
+ <boolean> true or false
+ <string> string()
+ <double> float()
+ <dateTime.iso8601> {date, string()}
+ <struct> {struct, [{Key, Value}]}
+ <array> {array, [Value]}
+ <base64> {base64, string()}
+
+ Read more about the XML-RPC data types in the XML-RPC
+ specification published by http://www.xmlrpc.org/.
+
+ Here are some examples on how Erlang format is converted
+ to XML:
+
+ 42 <int>42</int>
+
+ true <boolean>true</boolean>
+
+ "Kilroy was here"
+ <string>Kilroy was here</string>
+
+ 42.5 <double>42.5</double>
+
+ {date, "19980717T14:08:55"}
+ <dateTime.iso8601>19980717T14:08:55</date-
+ Time.iso8601>
+
+ {struct, [{foo, 42}, {bar, 4711}]}
+ <struct>
+ <member>
+ <name>foo</name><value><int>42</int></value>
+ </member>
+ <member>
+ <name>bar</name><value><int>4711</int></value>
+ </member>
+ </struct>
+
+ {array, [42, 42.5}
+ <array>
+ <data>
+ <value><int>42</i4></value>
+ <value><double>42.5</double></value>
+ </data>
+ </array>
+
+ {date, "19980717T14:08:55"}
+ <dateTime.iso8601>19980717T14:08:55</date-
+ Time.iso8601>
+
+
+EXAMPLES
+ You are strongly advised to inspect the example code in
+ the examples/ directory.
+
+ The first example (fib_server.erl) calculates Fibonacci
+ values and is a non-keepalive server. The second example
+ (echo_server.erl) echoes back any incoming parameters and
+ is a non-keepalive server. The third example
+ (date_server.erl) calculates calendar values for given
+ dates and is a keepalive server which uses the state vari-
+ able to provide login state and different timeout set-
+ tings. The fourth example (validator.erl) is a validation
+ server which can be used to validate the library using the
+ http://validator.xmlrpc.org/ service.
+
+ A snippet from the Fibonacci callback module in the exam-
+ ples/ directory:
+
+ handler(_State, {call, fib, [N]}) when integer(N) ->
+ {false, {response, [fib(N)]}};
+ handler(_State, Payload) ->
+ FaultString = lists:flatten(io_lib:format("Unknown call: ~p", [Payload])),
+ {false, {response, {fault, -1, FaultString}}}.
+
+ fib(0) -> 1;
+ fib(1) -> 1;
+ fib(N) -> fib(N-1)+fib(N-2).
+
+ and how it can be called:
+
+ 1> xmlrpc:call({127, 0, 0, 1}, 4567, "/", {call, fib, [0]}).
+ {ok,{response,[1]}}
+ 2> xmlrpc:call({127, 0, 0, 1}, 4567, "/", {call, fib, [4]}).
+ {ok,{response,[5]}}
+
+ Again: You are strongly advised to inspect the example
+ code in the examples/ directory.
+
+
+FILES
+ http://www.xmlrpc.org/
+ Home for the XML-RPC specification.
+
+ README Main README file for the library.
+
+ examples/
+ Example code
+
+AUTHOR
+ Joakim Grebeno - jocke@gleipnir.com
+
+
+
+jocke@gleipnir.com Jan 2003 XMLRPC(3)
Please sign in to comment.
Something went wrong with that request. Please try again.