XMLRPC::Client

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

• XMLRPC::Base64

• 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
            

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

 
               # File xmlrpc/client.rb, line 212
def timeout=(new_timeout)
  @timeout = new_timeout
  @http.read_timeout = @timeout
  @http.open_timeout = @timeout
end
            

Changes the user for the Basic Authentication header to new_user

 
               # File xmlrpc/client.rb, line 219
def user=(new_user)
  @user = new_user
  set_auth
end