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.481. JsonRpcClient Class Protocols
Protocol | Default Port | SSL? | Description |
|---|---|---|---|
| 80 | No | Unencrypted JSON-RPC protocol over HTTP |
| 443 | Yes | JSON-RPC protocol over HTTP with SSL/TLS encryption |
The JsonRpcClient supplies default values for HTTP headers as follows:
Table 4.482. JsonRpcClient Default, but Overridable Headers
Header | Default Value |
|---|---|
|
|
|
|
|
|
|
|
Table 4.483. JsonRpcClient Class Method Overview
|
Method |
Except? |
Description |
|---|---|---|
|
|
N |
Creates the JsonRpcClient object based on the parameters passed. |
|
N |
Destroys the JsonRpcClient object and closes any open connections. | |
|
Y |
Copying objects of this class is not supported, an exception will be thrown. | |
|
|
Y |
Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. |
|
|
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. |
|
| 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. |
|
| 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. |
|
| N | Sets a Queue object to receive HTTPClient and Socket events or clears the queue if no argument is passed. |
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.
JsonRpcClient::constructor(softbool $no_connect = False)
JsonRpcClient::constructor(hash $opts, bool $no_connect = False)
my JsonRpcClient $jrc(("url":"http://hostname/json"));
Table 4.484. Arguments for JsonRpcClient::constructor()
Argument | Description |
|---|---|
| an option hash, see HTTPClient::constructor() Option Hash Keys for valid keys in this hash. |
| If this optional argument is passed with a value of |
Destroys the JsonRpcClient object and closes any open connections.
delete $jrc;
Copying objects of this class is not supported, an exception will be thrown.
Table 4.485. Exceptions thrown by JsonRpcClient::copy()
|
err |
desc |
|---|---|
|
|
objects of this class may not be copied |
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.
JsonRpcClient::call(string $method, ...) returns any
$result = $jrc.call("method_name", $arg1, $arg2);
Table 4.486. Arguments for JsonRpcClient::call()
Argument | Description |
|---|---|
| The JSON-RPC method name to call |
| Optional arguments for the method. |
Table 4.487. Return Values for JsonRpcClient::call()
|
Return Type |
Description |
|---|---|
|
The information returned by the JSON-RPC method. |
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.
JsonRpcClient::callArgs(string $method, any $args) returns any
$result = $jrc.callArgs("method_name", $arg_list);
Table 4.489. Return Values for JsonRpcClient::callArgs()
|
Return Type |
Description |
|---|---|
|
The information returned by the JSON-RPC method. |
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.
JsonRpcClient::callWithInfo(reference $info, string $method, ...) returns any
$result = $jrc.callWithInfo(\$info, "method_name", $arg1, $arg2);
Table 4.491. Return Values for JsonRpcClient::callWithInfo()
|
Return Type |
Description |
|---|---|
|
The information returned by the JSON-RPC method. |
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.
JsonRpcClient::callArgsWithInfo(reference $info, string $method, any $args) returns any
$result = $jrc.callArgsWithInfo(\$info, "method_name", $arg_list);
Table 4.492. Arguments for JsonRpcClient::callArgsWithInfo()
Argument | Description |
|---|---|
| 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. |
| The JSON-RPC method name to call |
| An optional list of arguments (or single argument) for the method. |
Table 4.493. Return Values for JsonRpcClient::callArgsWithInfo()
|
Return Type |
Description |
|---|---|
|
The information returned by the JSON-RPC method. |
Sets a Queue object to receive HTTPClient and Socket events. To remove the event queue and stop monitoring events, pass NOTHING to the method. See Event Handling for more information.
JsonRpcClient::setEventQueue() returns nothing
JsonRpcClient::setEventQueue(Queue $queue) returns nothing
$jrc.setEventQueue($queue);