Skip to content
Browse files

edocified the documentation, added specs and updated author e-mail

  • Loading branch information...
1 parent 84dd1a3 commit c684562fc39015f20517c832cbf58d2a4870528a Richard Carlsson committed Sep 16, 2011
Showing with 363 additions and 370 deletions.
  1. +1 −1 LICENSE
  2. +3 −4 Makefile
  3. +3 −4 README
  4. +0 −4 TODO
  5. +0 −16 doc/Makefile
  6. +139 −0 doc/overview.edoc
  7. +0 −307 doc/xmlrpc.3
  8. +11 −3 src/Makefile
  9. +1 −1 src/log.hrl
  10. +174 −7 src/xmlrpc.erl
  11. +6 −2 src/xmlrpc_decode.erl
  12. +6 −2 src/xmlrpc_encode.erl
  13. +6 −2 src/xmlrpc_http.erl
  14. +7 −4 src/{tcp_serv.erl → xmlrpc_tcp_serv.erl}
  15. +6 −2 src/xmlrpc_util.erl
  16. +0 −11 xmlrpc.pub
View
2 LICENSE
@@ -1,4 +1,4 @@
-Copyright (C) 2003 Joakim Greben� <jocke@gleipnir.com>.
+Copyright (C) 2003 Joakim Greben� <jocke@tail-f.com>.
All rights reserved.
Redistribution and use in source and binary forms, with or without
View
7 Makefile
@@ -1,17 +1,16 @@
VSN=1.13
PUB_VSN="{1, 13}"
-.PHONY: all doc clean test release
+.PHONY: all docs clean test release
all:
(cd src;$(MAKE))
-doc:
- (cd doc;$(MAKE))
+docs:
+ (cd src;$(MAKE) docs)
clean:
(cd src;$(MAKE) clean)
- (cd doc;$(MAKE) clean)
test: all
(cd test;$(MAKE))
View
7 README
@@ -13,11 +13,10 @@ Run make to compile, then start Erlang as "erl -pa ./ebin".
You are now ready to try the client and server examples in the
examples/ directory.
-Do not forget to read doc/xmlrpc.3 (or xmlrpc.txt, xmlrpc.ps,
-xmlrpc.pdf) for a detailed API description.
+Run 'make docs' to get edoc-generated HTML documentation under doc/.
Get the latest version of this library at https://github.com/etnt/xmlrpc.
-The original author of this library was Joakim Grebenö. It is
-currently maintained by Torbjörn Törnkvist. Send questions and/or
+The original author of this library was Joakim Greben�. It is
+currently maintained by Torbj�rn T�rnkvist. Send questions and/or
suggestions to etnt@redhoterlang.com.
View
4 TODO
@@ -1,4 +0,0 @@
-* SSL
-* SOAP
-* Integration into either the inets, jnets or yaws web server.
-* Implmentation of the function inspection protocol.
View
16 doc/Makefile
@@ -1,16 +0,0 @@
-GROFF=groff
-PS2PDF=ps2pdf
-
-all: xmlrpc.txt xmlrpc.ps xmlrpc.pdf
-
-xmlrpc.txt: xmlrpc.3
- $(GROFF) -t -e -mandoc -Tascii xmlrpc.3 | col -bx > xmlrpc.txt
-
-xmlrpc.ps: xmlrpc.3
- $(GROFF) -t -e -mandoc -Tps xmlrpc.3 > xmlrpc.ps
-
-xmlrpc.pdf: xmlrpc.ps
- $(PS2PDF) xmlrpc.ps xmlrpc.pdf
-
-clean:
- rm -f xmlrpc.txt xmlrpc.ps xmlrpc.pdf
View
139 doc/overview.edoc
@@ -0,0 +1,139 @@
+@author Joakim Greben�
+@author Torbj�rn T�rnkvist
+@copyright 2003 Joakim Greben�
+
+@reference <a href="rfc2068.txt">RFC 2068</a>
+@reference <a href="xmlrpc_spec.txt">XML-RPC Specification by Dave Winer</a>
+@doc
+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/]
+
+The original author of this library was Joakim Greben�. It is
+currently maintained by Torbj�rn T�rnkvist. Send questions and/or
+suggestions to `etnt@redhoterlang.com'.
+
+== Callbacks ==
+
+When starting an XML-RPC server (see {@link xmlrpc:start_link/6}), you must
+specify a `Handler' argument, which is a tuple of two atoms `{Module,
+Function}'.
+
+It is up to you to ensure that `Function' in `Module' exists. 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'.
+```Module:Function ( State , Payload ) -> Result'''
+
+where `State' is any Erlang term and the returned `Result' is either a
+2-tuple `{KeepAlive, ResponsePayload}' or a 4-tuple `{KeepAlive, State,
+Timeout, ResponsePayload}'. (Note: `KeepAlive' <em>must</em> be `false' in a
+2-tuple and `true' in a 4-tuple.)
+
+The returned `KeepAlive' value decides if the connection to the client
+should be kept open or not - compare with the `KeepAlive' argument to {@link
+xmlrpc:call/6}.
+
+`State' can be used as a state variable by the callback function and changes
+made to it are propagated to the next call to `Module:Function/2'. The state
+variable is only meaningful if both the client and the server are
+keepalive-oriented. The `Timeout' specified in {@link xmlrpc:start_link/6}
+can be updated in the returned 4-tuple.
+
+If `KeepAlive' is `true' and no call arrives within `Timeout' milliseconds,
+the socket is closed. The socket may be closed by the client before the
+specified timeout.
+
+== Data Types ==
+
+The conversion of XML-RPC values in method arguments and
+return values is done as follows:
+
+```
+XML-RPC value Erlang representation
+----------------- ----------------
+<int> integer()
+<boolean> boolean()
+<string> string()
+<double> float()
+<dateTime.iso8601> {date, string()}
+<struct> {struct, [{Key::atom(), 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 the Erlang format is converted to XML:
+<dl>
+ <dt>`42'</dt>
+ <dd>`<int>42</int>'</dd>
+ <dt>`true'</dt>
+ <dd>`<boolean>true</boolean>'</dd>
+ <dt>`"Kilroy was here"'</dt>
+ <dd>`<string>Kilroy was here</string>'</dd>
+ <dt>`42.5'</dt>
+ <dd>`<double>42.5</double>'</dd>
+ <dt>`{date, "19980717T14:08:55"}'</dt>
+ <dd>`<dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>'</dd>
+ <dt>`{struct, [{foo, 42}, {bar, 4711}]}'</dt>
+ <dd>
+```<struct>
+ <member>
+ <name>foo</name><value><int>42</int></value>
+ </member>
+ <member>
+ <name>bar</name><value><int>4711</int></value>
+ </member>
+ </struct>'''</dd>
+ <dt>`{array, [42, 42.5}'</dt>
+ <dd>
+```<array>
+ <data>
+ <value><int>42</i4></value>
+ <value><double>42.5</double></value>
+ </data>
+ </array>'''</dd>
+ <dt>`{date, "19980717T14:08:55"}'</dt>
+ <dd>`<dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>'</dd>
+</dl>
+
+== Examples ==
+
+You are strongly advised to inspect the example code in the `examples'
+subdirectory:
+<dl>
+ <dt>`fib_server.erl'</dt>
+ <dd>A non-keepalive server, calculating Fibonacci values.</dd>
+ <dt>`echo_server.erl'</dt>
+ <dd>A non-keepalive server, echoing back any incoming parameters.</dd>
+ <dt>`date_server.erl'</dt>
+ <dd>A keepalive server, calculating calendar values for given dates
+ and uses the state variable to provide login state and different
+ timeout settings.</dd>
+ <dt>`validator.erl'</dt>
+ <dd>A validation server which can be used to validate the library
+ using the [http://validator.xmlrpc.org/] service.</dd>
+</dl>
+
+The following is a snippet from the Fibonacci callback module in the
+`examples/' 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 here is 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]}}
+'''
View
307 doc/xmlrpc.3
@@ -1,307 +0,0 @@
-.TH XMLRPC 3 "Jan 2003" "jocke@gleipnir.com" "ERLANG MODULE DEFINITION"
-.SH MODULE
-xmlrpc \- XML\-RPC library
-.SH 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
-\fIhttp://www.xmlrpc.org/\fR.
-.SH EXPORTS
-.BI "call(" Socket ", " URI ", " Payload )
-.br
-.BI "call(" Host ", " Port ", " URI ", " Payload )
-.br
-.BI "call(" Socket ", " URI ", " Payload ", " KeepAlive ", " Timeout )
-.br
-.BI "call(" Host ", " Port ", " URI ", " Payload ", " KeepAlive ", " Timeout ") -> " Result
-.RS
-.TP
-Types
-Socket = socket()
-.br
-URI = string()
-.br
-Payload = {call, Method, [Value]}
-.br
-Method = atom()
-.br
-Value = integer() | float() | string() | Boolean | ISO8601Date | Base64 | Struct | Array
-.br
-Boolean = true | false
-.br
-ISO8601Date = {date, string()}
-.br
-Base64 = {base64, string()}
-.br
-Struct = {struct, [{Key, Value}]}
-.br
-Key = atom()
-.br
-Array = {array, [Value]}
-.br
-Host = string() | ip()
-.br
-Port = integer()
-.br
-KeepAlive = true | false
-.br
-Timeout = integer()
-.br
-ResponsePayload = {response, [Value]} | {response, Fault}
-.br
-Fault = {fault, FaultCode, FaultString}
-.br
-FaultCode = integer()
-.br
-FaultString = string()
-.br
-Result = {ok, ResponsePayload} | {error, Reason} | {ok, Socket, ResponsePayload} | {error, Socket, Reason}
-.br
-Reason = term()
-.LP
-Calls an XML\-RPC server listening on \fIHost\fR:\fIPort\fR. The
-\fIURI\fR and \fIPayload\fR is used in the HTTP POST request being
-sent to the server. The \fIValue\fR is converted to XML (see \fBDATA
-TYPES\fR below) and is used as request body.
-.LP
-If \fIKeepAlive\fR is \fBtrue\fR a \fISocket\fR 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
-\fITimeout\fR milli-seconds \fB{error, timeout}\fR or \fB{error,
-\fISocket\fB, timeout}\fR is returned.
-.LP
-\fIKeepAlive\fR and \fITimeout\fR default to \fBfalse\fR and 60000
-milli-seconds.
-.LP
-See \fBEXAMPLES\fR section below.
-.RE
-.LP
-.BI "start_link(" Handler )
-.br
-.BI "start_link(" Port ", " MaxSessions ", " Timeout ", " Handler ", " State )
-.br
-.BI "start_link(" IP ", " Port ", " MaxSessions ", " Timeout ", " Handler ", " State ") -> " Result
-.RS
-.TP
-Types
-Handler = {Module, Function}
-.br
-Module = Function = atom()
-.br
-Port = MaxSessions = integer()
-.br
-Timeout = integer()
-.br
-State = term()
-.br
-IP = ip()
-.br
-Result = {ok, Pid} | {error, Reason}
-.br
-Pid = pid()
-.br
-Reason = term()
-.LP
-Starts an XML\-RPC server listening on \fIIP\fR:\fIPort\fR. If no
-\fIIP\fR address is given the server listens on \fIPort\fR for all
-available \fIIP\fR addresses. \fIMaxSessions\fR is used to restrict
-the number of concurrent connections. If \fIMaxSessions\fR is reached
-the server accepts no new connections for 5 seconds, i.e. blocking new
-connect attempts.
-.LP
-\fIHandler\fR is a callback, implemented by \fIModule\fR:\fIFunction\fR/2,
-which is used to instantiate an XML\-RPC server. The \fITimeout\fR
-value is used if the handler is keepalive oriented. \fIState\fR is the
-initial state given to \fIModule\fR:\fIFunction\fR/2. The resulting
-\fIPid\fR can be used as input to \fBxmlrpc:stop/1\fR.
-.LP
-See \fBModule:Function/2\fR and \fBEXAMPLES\fR below.
-.RE
-.LP
-.BI "stop(" Pid ") -> " Result
-.RS
-.TP
-Types
-Pid = pid()
-.br
-Result = void()
-.LP
-Stops a running XML\-RPC server.
-.RE
-.LP
-.IB Module : Function ( State ", " Payload ") -> " Result
-.RS
-.TP
-Types
-State = term()
-.br
-Payload = <See above>
-.br
-Result = {KeepAlive, ResponsePayload} | {KeepAlive, State, Timeout, ResponsePayload}
-.br
-KeepAlive = true | false
-.br
-ResponsePayload = <See above>
-.br
-Timeout = integer()
-.LP
-It is up to you to implement \fIFunction\fR clauses in \fIModule\fR to
-instantiate an XML\-RPC server. Every time an XML-RPC call arrives the
-\fIValue\fR in the \fIPayload\fR gets converted to Erlang format and
-is passed on to \fIModule\fR:\fIFunction\fR/2.
-.LP
-A \fIFunction\fR clause is supposed to return either a 2-tuple or a
-4-tuple. \fIKeepAlive\fR \fBmust\fR be \fBfalse\fR in a 2-tuple and
-\fBtrue\fR in a 4-tuple. \fIKeepAlive\fR decides if the connection to
-the client should be kept open or not, i.e. compare with the
-\fIKeepAlive\fR argument to \fBcall/{3,4,5,6}\fR above.
-.LP
-\fIState\fR can be used as a state variable by the callback function
-and changes made to it is propagated to the next call to
-\fIModule\fR:\fIFunction\fR/2. The state variable is only meaningful
-if both the client and the server is keepalive oriented. The
-\fITimeout\fR specified in \fBstart_link/{1,5,6}\fR can be updated in
-the returning 4-tuple.
-.LP
-If \fIKeepAlive\fR is \fBtrue\fR and no call arrives within
-\fITimeout\fR milli-seconds the socket is closed. The socket may be
-closed by the client before the specified timeout.
-.LP
-See \fBEXAMPLES\fR below.
-.RE
-.SH DATA TYPES
-The conversion of \fIValue\fR in \fIPayload\fR and
-\fIResponsePayload\fR (see above) is done as follows:
-.LP
-.ft CW
-.nf
-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()}
-.fi
-.ft
-.LP
-Read more about the XML\-RPC data types in the XML\-RPC specification
-published by \fIhttp://www.xmlrpc.org/\fR.
-.LP
-Here are some examples on how Erlang format is converted to XML:
-.TP
-.B
-42
-<int>42</int>
-.TP
-.B
-true
-<boolean>true</boolean>
-.TP
-.B
-"Kilroy was here"
-<string>Kilroy was here</string>
-.TP
-.B
-42.5
-<double>42.5</double>
-.TP
-.B
-{date, "19980717T14:08:55"}
-<dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>
-.TP
-.B
-{struct, [{foo, 42}, {bar, 4711}]}
-.ft CW
-.nf
-<struct>
- <member>
- <name>foo</name><value><int>42</int></value>
- </member>
- <member>
- <name>bar</name><value><int>4711</int></value>
- </member>
-</struct>
-.fi
-.ft
-.TP
-.B
-{array, [42, 42.5}
-.ft CW
-.nf
-<array>
- <data>
- <value><int>42</i4></value>
- <value><double>42.5</double></value>
- </data>
-</array>
-.fi
-.ft
-.TP
-.B
-{date, "19980717T14:08:55"}
-<dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>
-.RE
-.LP
-.SH EXAMPLES
-You are strongly advised to inspect the example code in the
-\fIexamples/\fR directory.
-.LP
-The first example (\fIfib_server.erl\fR) calculates Fibonacci values
-and is a non-keepalive server. The second example
-(\fIecho_server.erl\fR) echoes back any incoming parameters and is a
-non-keepalive server. The third example (\fIdate_server.erl\fR)
-calculates calendar values for given dates and is a keepalive server
-which uses the state variable to provide login state and different
-timeout settings. The fourth example (\fIvalidator.erl\fR) is a
-validation server which can be used to validate the library using the
-\fIhttp://validator.xmlrpc.org/\fR service.
-.LP
-A snippet from the Fibonacci callback module in the \fIexamples/\fR
-directory:
-.LP
-.ft CW
-.nf
-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).
-.fi
-.ft
-.LP
-and how it can be called:
-.LP
-.ft CW
-.nf
-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]}}
-.fi
-.ft
-.LP
-Again: You are strongly advised to inspect the example code in the
-\fIexamples/\fR directory.
-.LP
-.SH FILES
-.TP
-.I
-http://www.xmlrpc.org/
-Home for the XML\-RPC specification.
-.TP
-.I
-README
-Main README file for the library.
-.TP
-.I examples/
-Example code
-.SH AUTHOR
-Joakim Grebeno \- jocke@gleipnir.com
View
14 src/Makefile
@@ -7,13 +7,21 @@ endif
ERLC=erlc
ERLC_FLAGS=-W $(DEBUG_FLAGS) -o ../ebin
-MODULES=xmlrpc xmlrpc_decode xmlrpc_encode xmlrpc_http xmlrpc_util tcp_serv
+MODULES=xmlrpc xmlrpc_decode xmlrpc_encode xmlrpc_http xmlrpc_util xmlrpc_tcp_serv
EBIN_FILES=$(MODULES:%=../ebin/%.beam)
+ERL_FILES=$(MODULES:%=%.erl)
+INCLUDES=
-all: $(EBIN_FILES)
+all: $(EBIN_FILES)
../ebin/%.beam: %.erl log.hrl
$(ERLC) $(ERLC_FLAGS) $<
+docs: ../doc/index.html
+
+../doc/index.html: ../doc/overview.edoc $(ERL_FILES) $(INCLUDES)
+ erl -noshell -run edoc_run application "xmlrpc" '".."' '[]'
+
clean:
- rm -f $(EBIN_FILES)
+ rm -f $(EBIN_FILES) ../doc/*.html ../doc/edoc-info \
+ ../doc/stylesheet.css ../doc/erlang.png
View
2 src/log.hrl
@@ -1,4 +1,4 @@
-%% Copyright (C) 2003 Joakim Grebenö <jocke@gleipnir.com>.
+%% Copyright (C) 2003 Joakim Grebenö <jocke@tail-f.com>.
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
View
181 src/xmlrpc.erl
@@ -1,4 +1,4 @@
-%% Copyright (C) 2003 Joakim Grebenö <jocke@gleipnir.com>.
+%% Copyright (C) 2003 Joakim Grebenö <jocke@tail-f.com>.
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
@@ -24,8 +24,17 @@
%% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
%% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+%% @author Joakim Grebenö <jocke@tail-f.com>
+%% @author Torbjörn Törnkvist <etnt@redhoterlang.com>
+%% @copyright 2003 Joakim Grebenö
+
+%% TODO: Document the callback state functions
+%% TODO: SOAP
+%% TODO: Integration into either the inets, jnets or yaws web server.
+%% TODO: Implementation of the function inspection protocol.
+
-module(xmlrpc).
--author('jocke@gleipnir.com').
+
-export([call/3, call/4, call/5, call/6]).
-export([start_link/1, start_link/5, start_link/6, stop/1]).
@@ -79,41 +88,159 @@ cbs_opaque(#cback_state{}=C, Opaque) ->
C#cback_state{opaque = Opaque}.
+%% Type definitions
+
+-type socket() :: term().
+
+-type ip_address() :: inet:ip_address().
+
+-type host() :: string() | ip_address().
+
+-type iso8601date() :: {date, string()}.
+
+-type base64() :: {base64, string()}.
+
+-type uri() :: string().
+
+-type xmlrpc_value() :: integer() | float() | string() | boolean()
+ | iso8601date() | base64() | xmlrpc_struct() | xmlrpc_array().
+
+-type xmlrpc_struct() :: {struct, [{Key::atom(), Value::xmlrpc_value()}]}.
+
+-type xmlrpc_array() :: {array, [xmlrpc_value()]}.
+
+-type response_payload() :: {response, [xmlrpc_value()]}
+ | {response, {fault, Code::integer(),
+ Message::string()}}.
+
+-type call_result() :: {ok, response_payload()}
+ | {ok, socket(), response_payload()}
+ | {error, Reason::term()}
+ | {error, socket(), Reason::term()}.
+
+
%%%
%%% Quick and dirty solution for adding SSL support.
%%%
-define(SSL, ssl).
-ssl_call(Host, Port, URI) ->
+-spec ssl_call(Socket, URI, Payload) -> call_result()
+ when Socket :: socket(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]}.
+
+%% @equiv ssl_call(Socket, URI, Payload, false, 60000)
+%% @see ssl_call/5
+
+ssl_call(Socket, URI, Payload) ->
put(proto, ?SSL),
- call(Host, Port, URI).
+ call(Socket, URI, Payload).
+
+-spec ssl_call(Host, Port, URI, Payload) -> call_result()
+ when Host :: host(),
+ Port :: integer(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]}.
+
+%% @equiv ssl_call(Host, Port, URI, Payload, false, 60000)
+%% @see ssl_call/6
ssl_call(Host, Port, URI, Payload) ->
put(proto, ?SSL),
call(Host, Port, URI, Payload).
+-spec ssl_call(Socket, URI, Payload, KeepAlive, Timeout) -> call_result()
+ when Socket :: socket(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]},
+ KeepAlive :: boolean(),
+ Timeout :: integer().
+
+%% @doc Calls an XML-RPC server on an open SSL connection.
+%% @see ssl_call/6
+
ssl_call(Socket, URI, Payload, KeepAlive, Timeout) ->
put(proto, ?SSL),
call(Socket, URI, Payload, KeepAlive, Timeout).
+-spec ssl_call(Host, Port, URI, Payload, KeepAlive, Timeout) -> call_result()
+ when Host :: host(),
+ Port :: integer(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]},
+ KeepAlive :: boolean(),
+ Timeout :: integer().
+
+%% @doc Calls an SSL XML-RPC server listening on `Host:Port' over.
+%% @see call/6
+
ssl_call(Host, Port, URI, Payload, KeepAlive, Timeout) ->
put(proto, ?SSL),
call(Host, Port, URI, Payload, KeepAlive, Timeout).
+
%% Exported: call/{3,4,5,6}
+-spec call(Host, Port, URI, Payload) -> call_result()
+ when Host :: host(),
+ Port :: integer(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]}.
+
+%% @equiv call(Host, Port, URI, Payload, false, 60000)
+
call(Host, Port, URI, Payload) ->
call(Host, Port, URI, Payload, false, 60000).
+-spec call(Host, Port, URI, Payload, KeepAlive, Timeout) -> call_result()
+ when Host :: host(),
+ Port :: integer(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]},
+ KeepAlive :: boolean(),
+ Timeout :: integer().
+
+%% @doc Calls an XML-RPC server listening on `Host:Port'. The arguments
+%% `URI' and `Payload' are used in the HTTP POST request sent to the server.
+%% The `Arguments' are converted to XML for the 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' milliseconds
+%% `{error, timeout}' or `{error, Socket, timeout}' is returned.
+%%
+%% `KeepAlive' and `Timeout' default to `false' and `60000' milliseconds,
+%% respectively.
+%%
+%% @see ssl_call/6
+
call(Host, Port, URI, Payload, KeepAlive, Timeout) ->
case connect(Host, Port, [{active, false}]) of
{ok, Socket} -> call(Socket, {Host,URI}, Payload, KeepAlive, Timeout);
{error, Reason} when KeepAlive == false -> {error, Reason};
{error, Reason} -> {error, undefined, Reason}
end.
-call(Socket, URI, Payload) -> call(Socket, URI, Payload, false, 60000).
+-spec call(Socket, URI, Payload) -> call_result()
+ when Socket :: socket(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]}.
+
+%% @equiv call(Socket, URI, Payload, false, 60000)
+
+call(Socket, URI, Payload) ->
+ call(Socket, URI, Payload, false, 60000).
+
+-spec call(Socket, URI, Payload, KeepAlive, Timeout) -> call_result()
+ when Socket :: socket(),
+ URI :: uri(),
+ Payload :: {call, Method::atom(), Arguments::[xmlrpc_value()]},
+ KeepAlive :: boolean(),
+ Timeout :: integer().
+
+%% @doc Calls an XML-RPC server on an open connection.
+%% @see call/6
call(Socket, URI, Payload, KeepAlive, Timeout) ->
?DEBUG_LOG({decoded_call, Payload}),
@@ -244,23 +371,63 @@ get_payload(Socket, Timeout, ContentLength) ->
%% Exported: start_link/{1,5,6}
+-spec start_link(Handler) -> {ok, pid()} | {error, Reason::term()}
+ when Handler :: {Module::atom(), Function::atom()}.
+
+%% @equiv start_link(4567, 1000, 60000, Handler, undefined)
+
start_link(Handler) ->
start_link(4567, 1000, 60000, Handler, undefined).
+-spec start_link(Port, MaxSessions, Timeout, Handler, State) ->
+ {ok, pid()} | {error, Reason::term()}
+ when Port :: integer(),
+ MaxSessions :: integer(),
+ Timeout :: integer(),
+ Handler :: {Module::atom(), Function::atom()},
+ State :: term().
+
+%% @equiv start_link(all, Port, MaxSessions, Timeout, Handler, State)
+
start_link(Port, MaxSessions, Timeout, Handler, State) ->
start_link(all, Port, MaxSessions, Timeout, Handler, State).
+-spec start_link(IP, Port, MaxSessions, Timeout, Handler, State) ->
+ {ok, pid()} | {error, Reason::term()}
+ when IP :: ip_address(),
+ Port :: integer(),
+ MaxSessions :: integer(),
+ Timeout :: integer(),
+ Handler :: {Module::atom(), Function::atom()},
+ State :: term().
+
+%% @doc 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., blocks new connect attempts.
+%%
+%% `Handler' is a callback, implemented by `Module:Function/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 {@link
+%% xmlrpc:stop/1}.
+
start_link(IP, Port, MaxSessions, Timeout, Handler, State) ->
OptionList = [{active, false}, {reuseaddr, true}|ip(IP)],
SessionHandler = {xmlrpc_http, handler, [Timeout, Handler, State]},
- tcp_serv:start_link([Port, MaxSessions, OptionList, SessionHandler]).
+ xmlrpc_tcp_serv:start_link([Port, MaxSessions, OptionList, SessionHandler]).
ip(all) -> [];
ip(IP) when is_tuple(IP) -> [{ip, IP}].
%% Exported: stop/1
-stop(Pid) -> tcp_serv:stop(Pid).
+-spec stop(Pid::pid()) -> ok.
+
+%% @doc Stops a running XML-RPC server.
+
+stop(Pid) -> xmlrpc_tcp_serv:stop(Pid).
%%%
View
8 src/xmlrpc_decode.erl
@@ -1,4 +1,4 @@
-%% Copyright (C) 2003 Joakim Grebenö <jocke@gleipnir.com>.
+%% Copyright (C) 2003 Joakim Grebenö <jocke@tail-f.com>.
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
@@ -24,8 +24,12 @@
%% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
%% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+%% @private
+%% @author jocke@tail-f.com
+%% @copyright 2003 Joakim Grebenö
+
-module(xmlrpc_decode).
--author('jocke@gleipnir.com').
+
-export([payload/1]).
-include("log.hrl").
View
8 src/xmlrpc_encode.erl
@@ -1,4 +1,4 @@
-%% Copyright (C) 2003 Joakim Grebenö <jocke@gleipnir.com>.
+%% Copyright (C) 2003 Joakim Grebenö <jocke@tail-f.com>.
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
@@ -24,8 +24,12 @@
%% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
%% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+%% @private
+%% @author jocke@tail-f.com
+%% @copyright 2003 Joakim Grebenö
+
-module(xmlrpc_encode).
--author('jocke@gleipnir.com').
+
-export([payload/1]).
%% Exported: payload/1
View
8 src/xmlrpc_http.erl
@@ -1,4 +1,4 @@
-%% Copyright (C) 2003 Joakim Grebenö <jocke@gleipnir.com>.
+%% Copyright (C) 2003 Joakim Grebenö <jocke@tail-f.com>.
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
@@ -24,8 +24,12 @@
%% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
%% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+%% @private
+%% @author jocke@tail-f.com
+%% @copyright 2003 Joakim Grebenö
+
-module(xmlrpc_http).
--author('jocke@gleipnir.com').
+
-export([handler/4]).
-include("log.hrl").
View
11 src/tcp_serv.erl → src/xmlrpc_tcp_serv.erl
@@ -1,4 +1,4 @@
-%% Copyright (C) 2003 Joakim Grebenö <jocke@gleipnir.com>.
+%% Copyright (C) 2003 Joakim Grebenö <jocke@tail-f.com>.
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
@@ -24,9 +24,12 @@
%% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
%% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
--module(tcp_serv).
--vsn("1.13").
--author('jocke@gleipnir.com').
+%% @private
+%% @author jocke@tail-f.com
+%% @copyright 2003 Joakim Grebenö
+
+-module(xmlrpc_tcp_serv).
+
-export([start_link/1, start_link/2,
start/1, start/2,
stop/1, stop/2]).
View
8 src/xmlrpc_util.erl
@@ -1,4 +1,4 @@
-%% Copyright (C) 2003 Joakim Grebenö <jocke@gleipnir.com>.
+%% Copyright (C) 2003 Joakim Grebenö <jocke@tail-f.com>.
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
@@ -24,8 +24,12 @@
%% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
%% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+%% @private
+%% @author jocke@tail-f.com
+%% @copyright 2003 Joakim Grebenö
+
-module(xmlrpc_util).
--author('jocke@gleipnir.com').
+
-export([is_string/1, is_iso8601_date/1, is_base64/1]).
is_string([C|Rest]) when C >= 0, C =< 255 -> is_string(Rest);
View
11 xmlrpc.pub
@@ -1,11 +0,0 @@
-{author,"Joakim Greben�","jocke@gleipnir.com","030107"}.
-{name,"xmlrpc"}.
-{vsn,%VSN%}.
-{summary,"An XML-RPC client/server library"}.
-{keywords,["XML","XML-RPC","RPC"]}.
-{needs,[{"xmerl",{0,18}}]}.
-{abstract,
- "This is an HTTP 1.1 compliant XML-RPC library for Erlang. 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/."}.

0 comments on commit c684562

Please sign in to comment.
Something went wrong with that request. Please try again.