Qore json Module 1.8.2
Loading...
Searching...
No Matches
Qore::Json::JsonRpcClient Class Reference

The JsonRpcClient class provides easy access to JSON-RPC web services. More...

#include <QC_JsonRpcClient.dox.h>

Inherits HTTPClient.

Public Member Methods

hash call (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.
 
hash callArgs (string method, auto 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 callId (any id, string method,...)
 Calls a remote method with a call ID, taking all arguments after the method name for the method arguments and returns the response as qore data structure.
 
hash callIdArgsWithInfo (reference info, any id, 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 callIdWithInfo (reference info, any id, 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.
 
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.
 
 constructor ()
 Creates the JsonRpcClient object with no arguments.
 
 constructor (hash opts, softbool no_connect=False)
 Creates the JsonRpcClient object based on the parameters passed.
 
 copy ()
 Throws an exception; copying JsonRpcClient objects is currently not supported.
 
string getVersion ()
 Returns the JSON-RPC protocol version.
 
nothing setEventQueue ()
 clears the event queue for the JsonRpcClient object
 
nothing setEventQueue (Queue queue)
 sets the event queue for the JsonRpcClient object
 
nothing setVersion (string version)
 Sets the JSON-RPC protocol version.
 

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.

Thie object supports the following JSON-RPC protocol versions:

  • "2.0": the default; requests and responses will include the "jsonrpc" attribute assigned to the version number (this is true for any declared JSON-RPC protocol version >= 2)
  • "1.0": can be explicitly set in the JsonRpcClient::constructor() or by calling JsonRpcClient::setVersion()
Note
other JSON-RPC protocol versions can be used; for example the unpublished "1.1" version can be used as well, but support for JSON-RPC 1.1 is deprecated; for any JSON-RPC protocol version > 1.0 and < 2.0, the "version" attribute is serialized with the declared protocol version number (unlike with 2.0 or above, where the "jsonrpc" attribute contains this value)

The JsonRpcClient class understands the following protocol schemes in addition to the protocol schemes 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 application/json;charset=utf-8
User-Agent Qore-JSON-RPC-Client/1.7
Connection Keep-Alive
Note
  • if no default_path is given in the constructor(), then "JSON" is used
  • This class is not available with the PO_NO_NETWORK parse option.

Member Function Documentation

◆ call()

QoreValue JsonRpcClient::call ( 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.

Parameters
methodThe JSON-RPC method name to call
...the arguments to the call
Returns
a data structure corresponding to the JSON data returned by the JSON-RPC server
Exceptions
JSON-SERIALIZATION-ERRORcannot serialize value passed (ex: binary, object)
JSON-PARSE-ERRORsyntax error parsing JSON string
HTTP-CLIENT-TIMEOUTtimeout on response from HTTP server
HTTP-CLIENT-RECEIVE-ERRORerror communicating with HTTP server
Note
other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
Example:
hash result = jrc.call("method.name", arg1, arg2);
Since
json 1.7 this method calls with a hardcoded id value of 1

◆ callArgs()

hash Qore::Json::JsonRpcClient::callArgs ( string  method,
auto  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
methodThe JSON-RPC method name to call
argsAn 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-ERRORcannot serialize value passed (ex: binary, object)
JSON-PARSE-ERRORsyntax error parsing JSON string
HTTP-CLIENT-TIMEOUTtimeout on response from HTTP server
HTTP-CLIENT-RECEIVE-ERRORerror communicating with HTTP server
Note
other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
Example:
hash result = jrc.callArgs("method.name", arg_list);
Since
json 1.7 this method calls with a hardcoded id value of 1

◆ callArgsWithInfo()

hash Qore::Json::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
infoa 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
methodThe JSON-RPC method name to call
argsAn 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-ERRORcannot serialize value passed (ex: binary, object)
JSON-PARSE-ERRORsyntax error parsing JSON string
HTTP-CLIENT-TIMEOUTtimeout on response from HTTP server
HTTP-CLIENT-RECEIVE-ERRORerror communicating with HTTP server
Note
other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
Example:
hash info;
hash result = jrc.callArgsWithInfo(\info, "method.name", arg_list, 2);
Since
json 1.7 this method calls with a hardcoded id value of 1

◆ callId()

hash Qore::Json::JsonRpcClient::callId ( any  id,
string  method,
  ... 
)

Calls a remote method with a call ID, taking all arguments after the method name for the method arguments and returns the response as qore data structure.

Parameters
idthe id value for the call
methodThe JSON-RPC method name to call
...the arguments to the call
Returns
a data structure corresponding to the JSON data returned by the JSON-RPC server
Exceptions
JSON-SERIALIZATION-ERRORcannot serialize value passed (ex: binary, object)
JSON-PARSE-ERRORsyntax error parsing JSON string
HTTP-CLIENT-TIMEOUTtimeout on response from HTTP server
HTTP-CLIENT-RECEIVE-ERRORerror communicating with HTTP server
Note
other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
Example:
hash result = jrc.callId(1, "method.name", arg1, arg2);
Since
json 1.7

◆ callIdArgsWithInfo()

hash Qore::Json::JsonRpcClient::callIdArgsWithInfo ( reference  info,
any  id,
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
infoa 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
idthe id value for the call
methodThe JSON-RPC method name to call
argsAn 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-ERRORcannot serialize value passed (ex: binary, object)
JSON-PARSE-ERRORsyntax error parsing JSON string
HTTP-CLIENT-TIMEOUTtimeout on response from HTTP server
HTTP-CLIENT-RECEIVE-ERRORerror communicating with HTTP server
Note
other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
Example:
hash info;
hash result = jrc.callIdArgsWithInfo(\info, 4, "method.name", arg_list, 2);
Since
json 1.7

◆ callIdWithInfo()

hash Qore::Json::JsonRpcClient::callIdWithInfo ( reference  info,
any  id,
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
infoa 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
idthe id value for the call
methodThe JSON-RPC method name to call
Returns
a data structure corresponding to the JSON data returned by the JSON-RPC server
Exceptions
JSON-SERIALIZATION-ERRORcannot serialize value passed (ex: binary, object)
JSON-PARSE-ERRORsyntax error parsing JSON string
HTTP-CLIENT-TIMEOUTtimeout on response from HTTP server
HTTP-CLIENT-RECEIVE-ERRORerror communicating with HTTP server
Note
other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
Example:
hash info;
hash result = jrc.callIdWithInfo(\info, 3, "method.name", arg1, arg2);
Since
the id parameter was added in json 1.7

◆ callWithInfo()

hash Qore::Json::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
infoa 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
methodThe JSON-RPC method name to call
Returns
a data structure corresponding to the JSON data returned by the JSON-RPC server
Exceptions
JSON-SERIALIZATION-ERRORcannot serialize value passed (ex: binary, object)
JSON-PARSE-ERRORsyntax error parsing JSON string
HTTP-CLIENT-TIMEOUTtimeout on response from HTTP server
HTTP-CLIENT-RECEIVE-ERRORerror communicating with HTTP server
Note
other exceptions may be thrown related to communication errors (ex: SSL errors, etc)
Example:
hash info;
hash result = jrc.callWithInfo(\info, "method.name", arg1, arg2);
Since
json 1.7 this method calls with a hardcoded id value of 1

◆ constructor() [1/2]

Qore::Json::JsonRpcClient::constructor ( )

Creates the JsonRpcClient object with no arguments.

No connection is made because no connection parameters are set with this call; connection parameters must be set afterwards using the appropriate HTTPClient methods.

The JSON-RPC version is set to "2.0" by default with this variant of the constructor()

Example:
JsonRpcClient jrc();
jrc.setURL("http://localhost:8080");

◆ constructor() [2/2]

Qore::Json::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
optsHTTPClient constructor options:
  • 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)
  • default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL; if this option is not given and no path appears in the URL, then "JSON" is used instead
  • default_port: The default port number to connect to if none is given in the URL
  • http_version: Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing message headers
  • 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
  • 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)
  • url: A string giving the URL to connect to; if this option is not given and no path appears in the URL, then "JSON" is used instead
  • version: A string giving the JSON-RPC protocol version; default: "2.0"
no_connectpass 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:
JsonRpcClient jrc(("url": "http://authuser:authpass@otherhost:8080/JSONRPC"));
Since
json 1.7 added support for the "version" option

◆ copy()

Qore::Json::JsonRpcClient::copy ( )

Throws an exception; copying JsonRpcClient objects is currently not supported.

Exceptions
JSONRPCCLIENT-COPY-ERRORcopying JsonRpcClient objects is currently not supported

◆ getVersion()

string Qore::Json::JsonRpcClient::getVersion ( )

Returns the JSON-RPC protocol version.

Code Flags:
CONSTANT
Returns
the JSON-RPC protocol version
Since
json 1.7

◆ setEventQueue() [1/2]

nothing Qore::Json::JsonRpcClient::setEventQueue ( )

clears the event queue for the JsonRpcClient object

Example:
jrc.setEventQueue();

◆ setEventQueue() [2/2]

nothing Qore::Json::JsonRpcClient::setEventQueue ( Queue  queue)

sets the event queue for the JsonRpcClient object

Parameters
queuethe Queue object to receive network events from the JsonRpcClient object
Example:
Queue queue();
jrc.setEventQueue(queue);

◆ setVersion()

nothing Qore::Json::JsonRpcClient::setVersion ( string  version)

Sets the JSON-RPC protocol version.

Parameters
versionthe JSON-RPC protocol version
Since
json 1.7

The documentation for this class was generated from the following files: