4.11. XmlRpcClient Class

Note: This class is not available with the PO_NO_NETWORK parse option.

The XmlRpcClient class provides easy access to XML-RPC web services. This class inherits all public methods of the HTTPClient class. The inherited HTTPClient methods are not listed in this section, see the section on the HTTPClient class for more information on methods provided by the parent class. For low-level XML-RPC functions, see the XML-RPC functions in XML Functions.

The XmlRpcClient class understands the following protocols in addition to the protocols supported by the HTTPClient class:

Table 4.619. XmlRpcClient Class Protocols

Protocol

Default Port

SSL?

Description

xmlrpc

80

No

Unencrypted XML-RPC protocol over HTTP

xmlrpcs

443

Yes

XML-RPC protocol over HTTP with SSL/TLS encryption


The XmlRpcClient supplies default values for HTTP headers as follows:

Table 4.620. XmlRpcClient Default, but Overridable Headers

Header

Default Value

Accept

text/xml

Content-Type

text/xml

User-Agent

Qore XML-RPC Client v0.7.8

Connection

Keep-Alive


Table 4.621. XmlRpcClient Class Method Overview

Method

Except?

Description

XmlRpcClient::constructor()

Y

Creates the XmlRpcClient object based on the parameters passed.

XmlRpcClient::destructor()

N

Destroys the XmlRpcClient object and closes any open connections.

XmlRpcClient::copy()

Y

Copying objects of this class is not supported, an exception will be thrown.

XmlRpcClient::call()

Y

Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure.

XmlRpcClient::callArgs()

Y

Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure.

XmlRpcClient::callWithInfo()

Y

Same as the XmlRpcClient::call() except the first argument must be an lvalue reference, which is used as an output variable, where information about the HTTP request and response is written.

XmlRpcClient::callArgsWithInfo()

Y

Same as the XmlRpcClient::callArgs() except the first argument must be an lvalue reference, which is used as an output variable, where information about the HTTP request and response is written.


4.11.1. XmlRpcClient::constructor()

Synopsis

Creates the XmlRpcClient object based on the parameters passed and by default immediately attempts to establish a connection to the server (pass a boolean True value as the second argument to establish a connection on demand). See HTTPClient::constructor() and HTTPClient::connect() for information on possible exceptions.

Usage
new XmlRpcClient([opts, noconnect])
Example
$xrc = new XmlRpcClient(("url":"http://hostname/RPC2"));

Table 4.622. Arguments for XmlRpcClient::constructor()

Argument

Type

Description

[opts]

Hash

an option hash, see HTTPClient::constructor() Option Hash Keys for valid keys in this hash.

[noconnect]

Boolean

If this optional argument is passed with a value of True, then the object will not attempt to make a connection immediately to the remote socket, but instead will wait until a connection is required or manually established with the parent class' HTTPClient::connect() method.


Table 4.623. Return Values for XmlRpcClient::constructor()

Return Type

Description

Object

The XmlRpcClient object is returned


4.11.2. XmlRpcClient::destructor()

Synopsis

Destroys the XmlRpcClient object and closes any open connections.

Usage
delete lvalue
Example
delete $xrc;

Table 4.624. Arguments for XmlRpcClient::destructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.625. Return Values for XmlRpcClient::destructor()

Return Type

Description

n/a

This method returns no value


4.11.3. XmlRpcClient::copy()

Synopsis

Copying objects of this class is not supported, an exception will be thrown.

Table 4.626. Arguments for XmlRpcClient::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.627. Return Values for XmlRpcClient::copy()

Return Type

Description

n/a

This method returns no value


Table 4.628. Exceptions thrown by XmlRpcClient::copy()

err

desc

XMLRPCCLIENT-COPY-ERROR

objects of this class may not be copied


4.11.4. XmlRpcClient::call()

Synopsis

Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. See HTTPClient::send(), makeXMLRPCCallString(), and parseXMLRPCResponse() for information on possible exceptions.

Usage
XmlRpcClient::call(method_name, [args...])
Example
$result = $xrc.call("method.name", $arg1, $arg2);

Table 4.629. Arguments for XmlRpcClient::call()

Argument

Type

Description

method_name

String

The XML-RPC method name to call

[args...]

Any

Optional arguments for the method.


Table 4.630. Return Values for XmlRpcClient::call()

Return Type

Description

Hash

If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key.


4.11.5. XmlRpcClient::callArgs()

Synopsis

Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure. See HTTPClient::send(), makeXMLRPCCallString(), and parseXMLRPCResponse() for information on possible exceptions.

Usage
XmlRpcClient::callArgs(method_name, [arg_list])
Example
$result = $xrc.callArgs("method.name", $arg_list);

Table 4.631. Arguments for XmlRpcClient::callArgs()

Argument

Type

Description

method_name

String

The XML-RPC method name to call

[arg_list]

List or Any

An optional list (or single value) of arguments for the method.


Table 4.632. Return Values for XmlRpcClient::callArgs()

Return Type

Description

Hash

If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key.


4.11.6. XmlRpcClient::callWithInfo()

Synopsis

Like the XmlRpcClient::call() method, except requires an lvalue reference as the first argument that will be used as an output variable providing information about the HTTP request and response made to effect the XML-RPC call.

Usage
XmlRpcClient::callWithInfo(lvalue_ref, method_name, [args...])
Example
$result = $xrc.callWithInfo(\$info, "method.name", $arg1, $arg2);

Table 4.633. Arguments for XmlRpcClient::callWithInfo()

Argument

Type

Description

lvalue_ref

LValue Reference

A reference to an lvalue that will be used as an output variable providing information about the HTTP request and response made to effect the JSON-RPC call.

method_name

String

The XML-RPC method name to call

[args...]

Any

Optional arguments for the method.


Table 4.634. Return Values for XmlRpcClient::callWithInfo()

Return Type

Description

Hash

If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key.


4.11.7. XmlRpcClient::callArgsWithInfo()

Synopsis

Like the XmlRpcClient::callArgs() method, except requires an lvalue reference as the first argument that will be used as an output variable providing information about the HTTP request and response made to effect the XML-RPC call.

Usage
XmlRpcClient::callArgsWithInfo(lvalue_ref, method_name, [arg_list])
Example
$result = $xrc.callArgsWithInfo(\$info, "method.name", $arg_list);

Table 4.635. Arguments for XmlRpcClient::callArgsWithInfo()

Argument

Type

Description

lvalue_ref

LValue Reference

A reference to an lvalue that will be used as an output variable providing information about the HTTP request and response made to effect the JSON-RPC call.

method_name

String

The XML-RPC method name to call

[arg_list]

List or Any

An optional list (or single value) of arguments for the method.


Table 4.636. Return Values for XmlRpcClient::callArgswithInfo()

Return Type

Description

Hash

If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key.