Up: lib-jsonrpc [Contents][Index]
Each request results in a response, a JSON object sent back to the client. A response has the following members:
jsonrpc
A string with value "2.0"
.
id
The id
from the request. This is one reason why it is helpful to ensure that each request has a unique identifier.
result
If the request completed normally (i.e. did not cause an error or
failed) this member will be present and will contain the result
specified by the hook that handled the request. If a
request
member is present, the error
member, below,
will not be present.
error
The response is an error response. If the request caused an
error, failed or a handler asked for an error to be reported, this
member will be present and will contain a JSON object that
describes the error. If an error
member is present, the
result
member, above, will not be present.
The value of the error
member will be an object, with the
following members:
code
An integer code describing the error. Error code -32768
to
-32000
are reserved by the JSON-RPC standard.
The reserved error codes currently defined by the JSON-RPC
standard are: ‘Parse error’ (-32700
), ‘Invalid
Request’ (-32600
), ‘Method not found’
(-326601
), ‘Invalid params’ (-32602
), and
‘Internal error’ (-32603
).
‘Method not found’ will be reported if the request hook fails (unless there is a call hook and the request is one of the Prolog-style requests).
The server can also report one of the following errors:
-4711
This indicates a failure response. This is used when one of the Prolog-style requests causes a goal to fail. Note that this does not indicate that there was an error.
-4712
This is used when one of the Prolog-style requests causes an error exception to be thrown, i.e. this indicates that there was an error in one of the hooks.
-4713
This is used when a cut
or retry
request refers to a
request
that is not active (anymore).
message
A (short) string describing the error.
data
An optional value (primitive or structured) with additional information about the error.
Exported predicates:
jsonrpc_server_main(+StateIn, -StateOut, +RequestHook, +CallHook, +Options)
jsonrpc_server_main(+StateIn, -StateOut, +RequestHook, +Options)
This starts the server, with the specified initial state (StateIn), hooks, and options. See the module documentation for a description of the request hook and the (optional) call hook. When the server exits, the StateOut argument will be bound to the final value of the state.
If a CallHook is not specified, the “Prolog-style” requests will not be treated specially, i.e. the request hook can handle them as ordinary requests, if desired, otherwise they will just cause a ‘Method not found’ error response.
The RequestHook will be invoked as
RequestHook(Message, ResultDescription, StateIn, StateOut)
,
where Message is the JSON-RPC request, StateIn is the
current server state, and on success, ResultDescription
describes the result of invoking the hook, and StateOut is
the new server state. See the module documentation for retails.
The CallHook will be invoked as CallHook(Term,
Variables, ResultDescription, StateIn, StateOut)
, where
Term is a term as specified in a once
or call
request, Variables is the names and values of the variables
in the Term, the other arguments are similar as for the
RequestHook. See the module documentation for retails.
Options is a list of options, the valid options are:
in(InStream)
The (text) stream from which the server reads JSON data. The stream should use UTF-8 encoding for maximum compatibility with JSON.
out(OutStream)
The (text) stream to which the server writes JSON data. The stream should use UTF-8 encoding for maximum compatibility with JSON.
read_options(JSONReadOptions)
Extra options passed to json_read/3
when reading from the
InStream. The default is the empty list, and it is not
recommended to change this.
In addition to these extra options, a default set of options is also
passed to json_read/3
.
write_options(JSONWriteOptions)
Extra options passed to json_write/3
when writing to the
OutStream. The default is the empty list, and it is not
recommended to change this.
In addition to these extra options, a default set of options is also
passed to json_write/3
.
One of these default options is compact(true)
, which
ensures that each written response will be a single line.
logging(Boolean)
Whether to use logging (to user_error
). Boolean is
one of true
or false
(default).