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 |
---|---|---|---|
| 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.638. JsonRpcClient Default, but Overridable Headers
Header | Default Value |
---|---|
|
|
|
|
|
|
|
|
Table 4.639. 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. | |
N |
Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. | |
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. | |
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. |
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.
new JsonRpcClient([opts, noconnect]
)
$jrc = new JsonRpcClient(("url":"http://hostname/json"));
Table 4.640. Arguments for JsonRpcClient::constructor()
Argument | Type | Description |
---|---|---|
| Hash | an option hash, see HTTPClient::constructor() Option Hash Keys for valid keys in this hash. |
| 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 |
Destroys the JsonRpcClient object and closes any open connections.
delete lvalue
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 |
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 |
---|---|
|
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(method_name, [arg1, arg2...
)
$result = $jrc.call("method_name", $arg1, $arg2);
Table 4.647. Arguments for JsonRpcClient::call()
Argument |
Type |
Description |
---|---|---|
|
String |
The JSON-RPC method name to call |
|
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. |
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(method_name, [arg_list]
)
$result = $jrc.callArgs("method_name", $arg_list);
Table 4.649. Arguments for JsonRpcClient::callArgs()
Argument |
Type |
Description |
---|---|---|
|
String |
The JSON-RPC method name to call |
|
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. |
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(lvalue_reference, method_name, [arg1, arg2...
)
$result = $jrc.callWithInfo(\$info, "method_name", $arg1, $arg2);
Table 4.651. Arguments for JsonRpcClient::callWithInfo()
Argument |
Type |
Description |
---|---|---|
| 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. |
| String | The JSON-RPC method name to call |
|
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. |
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(lvalue_reference, method_name, [arg_list]
)
$result = $jrc.callArgsWithInfo(\$info, "method_name", $arg_list);
Table 4.653. Arguments for JsonRpcClient::callArgsWithInfo()
Argument |
Type |
Description |
---|---|---|
| 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. |
|
String |
The JSON-RPC method name to call |
|
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. |