10.21.4 Responses

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.

10.21.5 Predicates

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).