Copyright (C) 2001 by Michael Neumann (neumann@s-direktnet.de)
Released under the same term of license as Ruby.
require "xmlrpc/client"
server = XMLRPC::Client.new("www.ruby-lang.org", "/RPC2", 80)
begin
param = server.call("michael.add", 4, 5)
puts "4 + 5 = #{param}"
rescue XMLRPC::FaultException => e
puts "Error:"
puts e.faultCode
puts e.faultString
end
or
require "xmlrpc/client"
server = XMLRPC::Client.new("www.ruby-lang.org", "/RPC2", 80)
ok, param = server.call2("michael.add", 4, 5)
if ok then
puts "4 + 5 = #{param}"
else
puts "Error:"
puts param.faultCode
puts param.faultString
end
Class XMLRPC::Client provides remote procedure calls to a XML-RPC server.
After setting the connection-parameters with XMLRPC::Client.new which
creates a new XMLRPC::Client instance, you can execute a remote procedure
by sending the call or call2
message to this new instance. The given parameters indicate which method to
call on the remote-side and of course the parameters for the remote procedure.
XMLRPC::Client.new( host, path="/RPC2", port=80, proxy_addr=nil, proxy_port=nil )
Creates an object which represents the remote XML-RPC server on the
given host host. If the server is CGI-based, path is the
path to the CGI-script, which will be called, otherwise (in the
case of a standalone server) path should be "/RPC2".
port is the port on which the XML-RPC server listens.
If proxy_addr is given, then a proxy server listening at
proxy_addr is used. proxy_port is the port of the
proxy server.
XMLRPC::Client#call( method, *args )
Invokes the method named method with the parameters given by
args on the XML-RPC server.
The parameter method is converted into a String and should
be a valid XML-RPC method-name.
Each parameter of args must be of one of the following types,
where Hash, Struct and Array can contain any of these listed types:
Fixnum, Bignum
TrueClass, FalseClass (true, false)
String
Float
Hash, Struct
Array
Date, Time, XMLRPC::DateTime
XMLRPC::Base64
The method returns the return-value from the RPC
*1.
The type of the return-value is one of the above shown,
only that a Bignum is only allowed when it fits in 32-bit and
that a XML-RPC dateTime.iso8601 type is always returned as
a XMLRPC::DateTime object and
a Struct is never returned, only a Hash.
If the remote procedure returned a fault-structure, then a
XMLRPC::FaultException exception is raised, which has two accessor-methods
faultCode and faultString of type Integer and String.
XMLRPC::Client#call2( method, *args )
The difference between this method and call is, that
this method do not raise a XMLRPC::FaultException exception.
The method returns an array of two values. The first value indicates if
the second value is a return-value (true) or an object of type
XMLRPC::FaultException.
Both are explained in call.
XMLRPC::Client#proxy( prefix, *args )
Returns an object of class XMLRPC::Client::Proxy, initialized with
prefix and args. A proxy object returned by this method behaves
like XMLRPC::Client#call, i.e. a call on that object will raise a
XMLRPC::FaultException when a fault-structure is returned by that call.
XMLRPC::Client#proxy2( prefix, *args )
Almost the same like XMLRPC::Client#proxy only that a call on the returned
XMLRPC::Client::Proxy object behaves like XMLRPC::Client#call2, i.e.
a call on that object will return two parameters.
XMLRPC::Client#set_writer( writer )
Sets the XML writer to use for generating XML output.
Should be an instance of a class from module XMLRPC::XMLWriter.
If this method is not called, then XMLRPC::XMLWriter::DEFAULT_WRITER is used.
XMLRPC::Client#set_parser( parser )
Sets the XML parser to use for parsing XML documents.
Should be an instance of a class from module XMLRPC::XMLParser.
If this method is not called, then XMLRPC::XMLParser::DEFAULT_WRITER is used.
require "xmlrpc/client"
server = XMLRPC::Client.new("www.ruby-lang.org", "/RPC2", 80)
michael = server.proxy("michael")
michael2 = server.proxy("michael", 4)
# both calls should return the same value '9'.
p michael.add(4,5)
p michael2.add(5)
Class XMLRPC::Client::Proxy makes XML-RPC calls look nicer!
You can call any method onto objects of that class - the object handles
method_missing and will forward the method call to a XML-RPC server.
Don't use this class directly, but use instead method XMLRPC::Client#proxy or
XMLRPC::Client#proxy2.
XMLRPC::Client::Proxy.new( server, prefix, args=[], call=true, delim="." )
Creates an object which provides method_missing.
server must be of type XMLRPC::Client, which is the XML-RPC server to be used
for a XML-RPC call. prefix and delim will be prepended to the methodname
called onto this object. If call is true then XMLRPC::Client#call is used,
otherwise XMLRPC::Client#call2. args are arguments which are automatically given
to every XML-RPC call before the arguments provides through method_missing.
Every method call is forwarded to the XML-RPC server defined in new.
Note: Inherited methods from class Object cannot be used as XML-RPC names, because they get around
method_missing.
$Id: client.rb,v 1.30 2001/04/20 13:38:02 michael Exp $
*1stands for Remote Procedure Call