In Files

  • xmlrpc/client.rb

XMLRPC::Client

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

Constants

USER_AGENT

Attributes

http_header_extra[RW]

Add additional HTTP headers to the request

http_last_response[R]

Returns the Net::HTTPResponse object of the last RPC.

password[R]

Return the corresponding attributes.

timeout[R]

Return the corresponding attributes.

user[R]

Return the corresponding attributes.

Public Class Methods

new(host=nil, path=nil, port=nil, proxy_host=nil, proxy_port=nil, user=nil, password=nil, use_ssl=nil, timeout=nil) click to toggle source

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 81
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
            

Public Instance Methods

call(method, *args) click to toggle source

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

  • XMLRPC::Base64

  • A Ruby object which class includes XMLRPC::Marshallable (only if Config::ENABLE_MARSHALLABLE 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 259
def call(method, *args)
  ok, param = call2(method, *args)
  if ok
    param
  else
    raise param
  end
end
            
call2(method, *args) click to toggle source

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 277
def call2(method, *args)
  request = create().methodCall(method, *args)
  data = do_rpc(request, false)
  parser().parseMethodResponse(data)
end
            
call2_async(method, *args) click to toggle source

Same as #call2, but can be called concurrently.

See also #call_async

 
               # File xmlrpc/client.rb, line 311
def call2_async(method, *args)
  request = create().methodCall(method, *args)
  data = do_rpc(request, true)
  parser().parseMethodResponse(data)
end
            
call_async(method, *args) click to toggle source

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 299
def call_async(method, *args)
  ok, param = call2_async(method, *args)
  if ok
    param
  else
    raise param
  end
end
            
multicall(*methods) click to toggle source

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 326
def multicall(*methods)
  ok, params = multicall2(*methods)
  if ok
    params
  else
    raise params
  end
end
            
multicall2(*methods) click to toggle source

Same as #multicall, but returns two parameters instead of raising an XMLRPC::FaultException.

See #call2

 
               # File xmlrpc/client.rb, line 339
def multicall2(*methods)
  gen_multicall(methods, false)
end
            
multicall2_async(*methods) click to toggle source

Same as #multicall2, but can be called concurrently.

See also #multicall_async

 
               # File xmlrpc/client.rb, line 371
def multicall2_async(*methods)
  gen_multicall(methods, true)
end
            
multicall_async(*methods) click to toggle source

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 359
def multicall_async(*methods)
  ok, params = multicall2_async(*methods)
  if ok
    params
  else
    raise params
  end
end
            
new2(uri, proxy=nil, timeout=nil) click to toggle source

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 135
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
            
new3(hash={}) click to toggle source

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 174
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
            
password=(new_password) click to toggle source

Changes the password for the Basic Authentication header to new_password

 
               # File xmlrpc/client.rb, line 218
def password=(new_password)
  @password = new_password
  set_auth
end
            
proxy(prefix=nil, *args) click to toggle source

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 382
def proxy(prefix=nil, *args)
  Proxy.new(self, prefix, args, :call)
end
            
proxy2(prefix=nil, *args) click to toggle source

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 390
def proxy2(prefix=nil, *args)
  Proxy.new(self, prefix, args, :call2)
end
            
proxy2_async(prefix=nil, *args) click to toggle source

Same as #proxy2, but can be called concurrently.

See also #proxy_async

 
               # File xmlrpc/client.rb, line 417
def proxy2_async(prefix=nil, *args)
  Proxy.new(self, prefix, args, :call2_async)
end
            
proxy_async(prefix=nil, *args) click to toggle source

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 410
def proxy_async(prefix=nil, *args)
  Proxy.new(self, prefix, args, :call_async)
end
            
timeout=(new_timeout) click to toggle source

Sets the Net::HTTP#read_timeout and Net::HTTP#open_timeout to new_timeout

 
               # File xmlrpc/client.rb, line 204
def timeout=(new_timeout)
  @timeout = new_timeout
  @http.read_timeout = @timeout
  @http.open_timeout = @timeout
end
            
user=(new_user) click to toggle source

Changes the user for the Basic Authentication header to new_user

 
               # File xmlrpc/client.rb, line 211
def user=(new_user)
  @user = new_user
  set_auth
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.

blog comments powered by Disqus