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 XMLRPC::Client#call or XMLRPC::Client#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
No documentation available
Attributes
Read

Returns the Net::HTTP object for the client. If you want to change HTTP client options except header, cookie, timeout, user and password, use Net::HTTP directly.

Since 2.1.0.

Read & Write

Add additional HTTP headers to the request

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

Read & Write

Get and set the HTTP Cookie header.

Read

Return the corresponding attributes.

Read

Return the corresponding attributes.

Read

Return the corresponding attributes.

Class Methods

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.

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.

Receives a Hash and calls XMLRPC::Client.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

An alias for new3
Instance Methods

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:

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.

The difference between this method and XMLRPC::Client#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 XMLRPC::Client#call.

Simple to remember: The “2” in “call2” denotes the number of values it returns.

Same as XMLRPC::Client#call2, but can be called concurrently.

See also XMLRPC::Client#call_async

Similar to XMLRPC::Client#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)
}
No documentation available
No documentation available
No documentation available

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]

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

See XMLRPC::Client#call2

Same as XMLRPC::Client#multicall2, but can be called concurrently.

See also XMLRPC::Client#multicall_async

Similar to XMLRPC::Client#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)
}
No documentation available
No documentation available

Changes the password for the Basic Authentication header to new_password

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.

Almost the same like XMLRPC::Client#proxy only that a call on the returned XMLRPC::Client::Proxy object will return two parameters.

See XMLRPC::Client#call2

Same as XMLRPC::Client#proxy2, but can be called concurrently.

See also XMLRPC::Client#proxy_async

Similar to XMLRPC::Client#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)
}
No documentation available

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

Changes the user for the Basic Authentication header to new_user