The JsonRpcClient class provides easy access to JSON-RPC web services.
More...
List of all members.
Public Member Functions |
| constructor () |
| Creates the JsonRpcClient object based on the parameters passed.
|
| constructor (hash $opts, softbool $no_connect=False) |
| Creates the JsonRpcClient object based on the parameters passed.
|
Qore::JsonRpcClient | copy () |
| Throws an exception; copying JsonRpcClient objects is currently not supported.
|
hash | callArgs (string $method, any $args) |
| Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure.
|
hash | callArgsWithInfo (reference $info, string $method, any $args) |
| Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call.
|
hash | callWithInfo (reference $info, string $method,...) |
| Calls a remote method taking all arguments after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call.
|
nothing | setEventQueue () |
| clears the event queue for the JsonRpcClient object
|
nothing | setEventQueue (Queue $queue) |
| sets the event queue for the JsonRpcClient object
|
Detailed Description
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 documentation for the HTTPClient class for more information on methods provided by the parent class. For a list of low-level JSON-RPC functions, see JSON-RPC.
The JsonRpcClient class understands the following protocols in addition to the protocols supported by the HTTPClient class:
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:
JsonRpcClient Default, but Overridable Headers
Header | Default Value |
Accept | text/json |
Content-Type | text/json |
User-Agent | Qore JSON-RPC Client v1.0 |
Connection | Keep-Alive |
- Note:
- This class is not available with the PO_NO_NETWORK parse option.
Member Function Documentation
hash Qore::JsonRpcClient::callArgs |
( |
string |
$method, |
|
|
any |
$args |
|
) |
| |
Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure.
- Parameters:
-
$method | The JSON-RPC method name to call |
$args | An optional list of arguments (or single argument) for the method |
- Returns:
- a data structure corresponding to the JSON data returned by the JSON-RPC server
- Exceptions:
-
JSON-SERIALIZATION-ERROR | cannot serialize value passed (ex: binary, object) |
JSON-PARSE-ERROR | syntax error parsing JSON string |
HTTP-CLIENT-TIMEOUT | timeout on response from HTTP server |
HTTP-CLIENT-RECEIVE-ERROR | error communicating with HTTP server |
- Note:
- other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
- Example:
my hash $result = $jrc.callArgs("method.name", $arg_list);
hash Qore::JsonRpcClient::callArgsWithInfo |
( |
reference |
$info, |
|
|
string |
$method, |
|
|
any |
$args |
|
) |
| |
Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call.
- Parameters:
-
$info | a reference to a hash that provides the following keys on output giving technical information about the HTTP call:
request: the literal outgoing request body sent
request-uri : the first line of the HTTP request
headers: a hash of HTTP headers in the outgoing request
response-uri : the first line of the HTTP response
response: the literal response body received from the server
response_headers: a hash of headers received in the response
|
$method | The JSON-RPC method name to call |
$args | An optional list of arguments (or single argument) for the method |
- Returns:
- a data structure corresponding to the JSON data returned by the JSON-RPC server
- Exceptions:
-
JSON-SERIALIZATION-ERROR | cannot serialize value passed (ex: binary, object) |
JSON-PARSE-ERROR | syntax error parsing JSON string |
HTTP-CLIENT-TIMEOUT | timeout on response from HTTP server |
HTTP-CLIENT-RECEIVE-ERROR | error communicating with HTTP server |
- Note:
- other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
- Example:
my hash $info;
my hash $result = $jrc.callArgsWithInfo(\$info, "method.name", $arg_list);
hash Qore::JsonRpcClient::callWithInfo |
( |
reference |
$info, |
|
|
string |
$method, |
|
|
|
... |
|
) |
| |
Calls a remote method taking all arguments after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call.
- Parameters:
-
$info | a reference to a hash that provides the following keys on output giving technical information about the HTTP call:
request: the literal outgoing request body sent
request-uri : the first line of the HTTP request
headers: a hash of HTTP headers in the outgoing request
response-uri : the first line of the HTTP response
response: the literal response body received from the server
response_headers: a hash of headers received in the response
|
$method | The JSON-RPC method name to call |
- Returns:
- a data structure corresponding to the JSON data returned by the JSON-RPC server
- Exceptions:
-
JSON-SERIALIZATION-ERROR | cannot serialize value passed (ex: binary, object) |
JSON-PARSE-ERROR | syntax error parsing JSON string |
HTTP-CLIENT-TIMEOUT | timeout on response from HTTP server |
HTTP-CLIENT-RECEIVE-ERROR | error communicating with HTTP server |
- Note:
- other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
- Example:
my hash $info;
my hash $result = $jrc.callWithInfo(\$info, "method.name", $arg1, $arg2);
Qore::JsonRpcClient::constructor |
( |
hash |
$opts, |
|
|
softbool |
$no_connect = False |
|
) |
| |
Creates the JsonRpcClient object based on the parameters passed.
By default the object will immediately attempt to establish a connection to the server
- Parameters:
-
$opts | HTTPClient constructor options:
url: A string giving the URL to connect to.
default_port: The default port number to connect to if none is given in the URL.
protocols: A hash describing new protocols, the key is the protocol name and the value is either an integer giving the default port number or a hash with 'port' and 'ssl' keys giving the default port number and a boolean value to indicate that an SSL connection should be established.
http_version: Either '1 .0' or '1 .1' for the claimed HTTP protocol version compliancy in outgoing message headers.
default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL.
max_redirects: The maximum number of redirects before throwing an exception (the default is 5).
proxy: The proxy URL for connecting through a proxy.
timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 5m )
connect_timeout: The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: 30s )
|
$no_connect | pass a boolean True value argument to suppress the automatic connection and establish a connection on demand with the first request |
- See also:
- HTTPClient::constructor() and HTTPClient::connect() for information on possible exceptions
- Example:
my JsonRpcClient $jrc(("url": "http://authuser:authpass@otherhost:8080/JSONRPC"));
Qore::JsonRpcClient::constructor |
( |
) |
|
Creates the JsonRpcClient object based on the parameters passed.
No connection is made because no connection parameters are set with this call; connection parameters must be set afterwards using the appropriate HTTPClient methods.
- Example:
my JsonRpcClient $jrc();
$jrc.setURL("http://localhost:8080");
Throws an exception; copying JsonRpcClient objects is currently not supported.
- Exceptions:
-
JSONRPCCLIENT-COPY-ERROR | copying JsonRpcClient objects is currently not supported |
nothing Qore::JsonRpcClient::setEventQueue |
( |
Queue |
$queue ) |
|
sets the event queue for the JsonRpcClient object
- Parameters:
-
$queue | the Queue object to receive network events from the JsonRpcClient object |
- Example:
my Queue $queue();
$jrc.setEventQueue($queue);
nothing Qore::JsonRpcClient::setEventQueue |
( |
) |
|
The documentation for this class was generated from the following file: