Provides remote procedure calls to a XML-RPC server.
After setting the connection-parameters with ::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.
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
Creates an object which represents the remote XML-RPC server on the given
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_host
is given, then a proxy server listening at
proxy_host
is used. proxy_port
is the port of the
proxy server.
Default values for host
, path
and
port
are ‘localhost’, ‘/RPC2’ and ‘80’ respectively using SSL
‘443’.
If user
and password
are given, each time a
request is sent, an Authorization header is sent. Currently only Basic
Authentication is implemented, no Digest.
If use_ssl
is set to true
, communication over SSL
is enabled.
Parameter timeout
is the time to wait for a XML-RPC response,
defaults to 30.
# File xmlrpc/client.rb, line 82 def initialize(host=nil, path=nil, port=nil, proxy_host=nil, proxy_port=nil, user=nil, password=nil, use_ssl=nil, timeout=nil) @http_header_extra = nil @http_last_response = nil @cookie = nil @host = host || "localhost" @path = path || "/RPC2" @proxy_host = proxy_host @proxy_port = proxy_port @proxy_host ||= 'localhost' if @proxy_port != nil @proxy_port ||= 8080 if @proxy_host != nil @use_ssl = use_ssl || false @timeout = timeout || 30 if use_ssl require "net/https" @port = port || 443 else @port = port || 80 end @user, @password = user, password set_auth # convert ports to integers @port = @port.to_i if @port != nil @proxy_port = @proxy_port.to_i if @proxy_port != nil # HTTP object for synchronous calls @http = net_http(@host, @port, @proxy_host, @proxy_port) @http.use_ssl = @use_ssl if @use_ssl @http.read_timeout = @timeout @http.open_timeout = @timeout @parser = nil @create = nil end
Creates an object which represents the remote XML-RPC server at the given
uri
. The URI should have a host, port, path, user and
password. Example: user:password@host:port/path
Raises an ArgumentError if the uri
is invalid, or if the
protocol isn’t http or https.
If a proxy
is given it should be in the form of “host:port”.
The optional timeout
defaults to 30 seconds.
# File xmlrpc/client.rb, line 136 def new2(uri, proxy=nil, timeout=nil) begin url = URI(uri) rescue URI::InvalidURIError => e raise ArgumentError, e.message, e.backtrace end unless URI::HTTP === url raise ArgumentError, "Wrong protocol specified. Only http or https allowed!" end proto = url.scheme user = url.user passwd = url.password host = url.host port = url.port path = url.path.empty? ? nil : url.request_uri proxy_host, proxy_port = (proxy || "").split(":") proxy_port = proxy_port.to_i if proxy_port self.new(host, path, port, proxy_host, proxy_port, user, passwd, (proto == "https"), timeout) end
Receives a Hash and calls ::new with the corresponding values.
The hash
parameter has following case-insensitive keys:
host
path
port
proxy_host
proxy_port
user
password
use_ssl
timeout
# File xmlrpc/client.rb, line 175 def new3(hash={}) # convert all keys into lowercase strings h = {} hash.each { |k,v| h[k.to_s.downcase] = v } self.new(h['host'], h['path'], h['port'], h['proxy_host'], h['proxy_port'], h['user'], h['password'], h['use_ssl'], h['timeout']) end
Invokes the method named method
with the parameters given by
args
on the XML-RPC server.
The method
parameter 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, Symbol
Float
Hash, Struct
Array
Date, Time, XMLRPC::DateTime
A Ruby object which class includes XMLRPC::Marshallable (only if
Config::ENABLE_MARSHALLING is true
). That object is converted
into a hash, with one additional key/value pair
_class___
which contains the class name for restoring
that object later.
The method returns the return-value from the Remote Procedure Call.
The type of the return-value is one of the types shown above.
A Bignum is only allowed when it fits in 32-bit. A XML-RPC
dateTime.iso8601
type is always returned as a XMLRPC::DateTime object. Struct is never returned,
only a Hash, the same for a Symbol, where as a String is always returned.
XMLRPC::Base64 is returned as a String from
xmlrpc4r version 1.6.1 on.
If the remote procedure returned a fault-structure, then a XMLRPC::FaultException exception is raised,
which has two accessor-methods faultCode
an Integer, and
faultString
a String.
# File xmlrpc/client.rb, line 267 def call(method, *args) ok, param = call2(method, *args) if ok param else raise param end end
The difference between this method and #call is, that this method will NOT raise a XMLRPC::FaultException exception.
The method returns an array of two values. The first value indicates if the
second value is true
or an XMLRPC::FaultException.
Both are explained in #call.
Simple to remember: The “2” in “call2” denotes the number of values it returns.
# File xmlrpc/client.rb, line 285 def call2(method, *args) request = create().methodCall(method, *args) data = do_rpc(request, false) parser().parseMethodResponse(data) end
Same as #call2, but can be called concurrently.
See also #call_async
# File xmlrpc/client.rb, line 319 def call2_async(method, *args) request = create().methodCall(method, *args) data = do_rpc(request, true) parser().parseMethodResponse(data) end
Similar to #call, however can be
called concurrently and use a new connection for each request. In contrast
to the corresponding method without the _async
suffix, which
use connect-alive (one connection for all requests).
Note, that you have to use Thread to call these methods concurrently. The following example calls two methods concurrently:
Thread.new { p client.call_async("michael.add", 4, 5) } Thread.new { p client.call_async("michael.div", 7, 9) }
# File xmlrpc/client.rb, line 307 def call_async(method, *args) ok, param = call2_async(method, *args) if ok param else raise param end end
You can use this method to execute several methods on a XMLRPC server which support the multi-call extension.
s.multicall( ['michael.add', 3, 4], ['michael.sub', 4, 5] ) # => [7, -1]
# File xmlrpc/client.rb, line 334 def multicall(*methods) ok, params = multicall2(*methods) if ok params else raise params end end
Same as #multicall, but returns two parameters instead of raising an XMLRPC::FaultException.
See #call2
# File xmlrpc/client.rb, line 347 def multicall2(*methods) gen_multicall(methods, false) end
Same as #multicall2, but can be called concurrently.
See also #multicall_async
# File xmlrpc/client.rb, line 379 def multicall2_async(*methods) gen_multicall(methods, true) end
Similar to #multicall, however
can be called concurrently and use a new connection for each request. In
contrast to the corresponding method without the _async
suffix, which use connect-alive (one connection for all requests).
Note, that you have to use Thread to call these methods concurrently. The following example calls two methods concurrently:
Thread.new { p client.multicall_async("michael.add", 4, 5) } Thread.new { p client.multicall_async("michael.div", 7, 9) }
# File xmlrpc/client.rb, line 367 def multicall_async(*methods) ok, params = multicall2_async(*methods) if ok params else raise params end end
Changes the password for the Basic Authentication header to
new_password
# File xmlrpc/client.rb, line 226 def password=(new_password) @password = new_password set_auth end
Returns an object of class XMLRPC::Client::Proxy, initialized with
prefix
and args
.
A proxy object returned by this method behaves like #call, i.e. a call on that object will raise a XMLRPC::FaultException when a fault-structure is returned by that call.
# File xmlrpc/client.rb, line 390 def proxy(prefix=nil, *args) Proxy.new(self, prefix, args, :call) end
Almost the same like #proxy only that a call on the returned XMLRPC::Client::Proxy object will return two parameters.
See #call2
# File xmlrpc/client.rb, line 398 def proxy2(prefix=nil, *args) Proxy.new(self, prefix, args, :call2) end
Same as #proxy2, but can be called concurrently.
See also #proxy_async
# File xmlrpc/client.rb, line 425 def proxy2_async(prefix=nil, *args) Proxy.new(self, prefix, args, :call2_async) end
Similar to #proxy, however can be
called concurrently and use a new connection for each request. In contrast
to the corresponding method without the _async
suffix, which
use connect-alive (one connection for all requests).
Note, that you have to use Thread to call these methods concurrently. The following example calls two methods concurrently:
Thread.new { p client.proxy_async("michael.add", 4, 5) } Thread.new { p client.proxy_async("michael.div", 7, 9) }
# File xmlrpc/client.rb, line 418 def proxy_async(prefix=nil, *args) Proxy.new(self, prefix, args, :call_async) end
Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.
If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.
If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.
If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.