4.12. JsonRpcClient Class

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

The JsonRpcClient class provides easy access to JSON-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 JSON-RPC functions, see the JSON-RPC functions in JSON Functions.

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

Table 4.637. JsonRpcClient Class Protocols

Protocol

Default Port

SSL?

Description

jsonrpc

80

No

Unencrypted JSON-RPC protocol over HTTP

jsonrpcs

443

Yes

JSON-RPC protocol over HTTP with SSL/TLS encryption


The JsonRpcClient supplies default values for HTTP headers as follows:

Table 4.638. JsonRpcClient Default, but Overridable Headers

Header

Default Value

Accept

application/json

Content-Type

application/json

User-Agent

Qore JSON-RPC Client v0.7.6

Connection

Keep-Alive


Table 4.639. JsonRpcClient Class Method Overview

Method

Except?

Description

JsonRpcClient::constructor()

N

Creates the JsonRpcClient object based on the parameters passed.

JsonRpcClient::destructor()

N

Destroys the JsonRpcClient object and closes any open connections.

JsonRpcClient::copy()

Y

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

JsonRpcClient::call()

N

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

JsonRpcClient::callArgs()

N

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

JsonRpcClient::callWithInfo()

Y

Same as the JsonRpcClient::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.

JsonRpcClient::callArgsWithInfo()

Y

Same as the JsonRpcClient::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.12.1. JsonRpcClient::constructor()

Synopsis

Creates the JsonRpcClient 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 JsonRpcClient([opts, noconnect])
Example
$jrc = new JsonRpcClient(("url":"http://hostname/json"));

Table 4.640. Arguments for JsonRpcClient::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.641. Return Values for JsonRpcClient::constructor()

Return Type

Description

Object

The JsonRpcClient object is returned


4.12.2. JsonRpcClient::destructor()

Synopsis

Destroys the JsonRpcClient object and closes any open connections.

Usage
delete lvalue
Example
delete $jrc;

Table 4.642. Arguments for JsonRpcClient::destructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.643. Return Values for JsonRpcClient::destructor()

Return Type

Description

n/a

This method returns no value


4.12.3. JsonRpcClient::copy()

Synopsis

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

Table 4.644. Arguments for JsonRpcClient::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.645. Return Values for JsonRpcClient::copy()

Return Type

Description

n/a

This method returns no value


Table 4.646. Exceptions thrown by JsonRpcClient::copy()

err

desc

JSONRPCCLIENT-COPY-ERROR

objects of this class may not be copied


4.12.4. JsonRpcClient::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(), makeJSONRPCRequestString(), and parseJSON() for information on possible exceptions.

Usage
JsonRpcClient::call(method_name, [arg1, arg2...)
Example
$result = $jrc.call("method_name", $arg1, $arg2);

Table 4.647. Arguments for JsonRpcClient::call()

Argument

Type

Description

method_name

String

The JSON-RPC method name to call

[arg_list]

List or Any

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


Table 4.648. Return Values for JsonRpcClient::call()

Return Type

Description

Hash

The information returned by the JSON-RPC method.


4.12.5. JsonRpcClient::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(), makeJSONRPCRequestString(), and parseJSON() for information on possible exceptions.

Usage
JsonRpcClient::callArgs(method_name, [arg_list])
Example
$result = $jrc.callArgs("method_name", $arg_list);

Table 4.649. Arguments for JsonRpcClient::callArgs()

Argument

Type

Description

method_name

String

The JSON-RPC method name to call

[arg_list]

List or Any

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


Table 4.650. Return Values for JsonRpcClient::callArgs()

Return Type

Description

Any

The information returned by the JSON-RPC method.


4.12.6. JsonRpcClient::callWithInfo()

Synopsis

Like the JsonRpcClient::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 JSON-RPC call.

Usage
JsonRpcClient::callWithInfo(lvalue_reference, method_name, [arg1, arg2...)
Example
$result = $jrc.callWithInfo(\$info, "method_name", $arg1, $arg2);

Table 4.651. Arguments for JsonRpcClient::callWithInfo()

Argument

Type

Description

lvalue_reference

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 JSON-RPC method name to call

[arg_list]

List or Any

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


Table 4.652. Return Values for JsonRpcClient::callWithInfo()

Return Type

Description

Hash

The information returned by the JSON-RPC method.


4.12.7. JsonRpcClient::callArgswithInfo()

Synopsis

Like the JsonRpcClient::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 JSON-RPC call.

Usage
JsonRpcClient::callArgsWithInfo(lvalue_reference, method_name, [arg_list])
Example
$result = $jrc.callArgsWithInfo(\$info, "method_name", $arg_list);

Table 4.653. Arguments for JsonRpcClient::callArgsWithInfo()

Argument

Type

Description

lvalue_reference

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 JSON-RPC method name to call

[arg_list]

List or Any

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


Table 4.654. Return Values for JsonRpcClient::callArgsWithInfo()

Return Type

Description

Any

The information returned by the JSON-RPC method.