Usage of libjsonrpc

LibJSONRPC — it is the library that provide for applications additional interface — web-interface via JSON-RPC protocol.

Its interface consists of three main parts:

• JSON functions
• JSON-RPC functions
• JSON-RPC transport functions

1. JSON functions

For dealing with JSON data uses struct json_object

struct json_object *json_int_new(int i);

struct json_object *json_double_new(double d);

struct json_object *json_boolean_new(boolean b);

struct json_object *json_string_new(char *s);

struct json_object *json_string_new_len(char *s, size_t len);

struct json_object *json_null_new();

This group of functions creates JSON data from C native data types

int json_int_get(struct json_object *obj);

double json_double_get(struct json_object *obj);

boolean json_boolean_get(struct json_object *obj);

char *json_string_get(struct json_object *obj);

This group of functions retrieves C native data values from its JSON representation

struct json_object *json_array_new();

int json_array_length(struct json_object *obj);

struct json_object *json_array_get(struct json_object *obj, int i);

int json_array_add(struct json_object *obj, struct json_object *val);

void json_array_del(struct json_object *obj, int ind);

This group of functions deals with JSON arrays

struct json_object *json_object_new();

struct json_object *json_object_get(struct json_object *obj, char *key);

void json_object_del(struct json_object *obj, char *key);

int json_object_add(struct json_object *obj, char *key, struct json_object *val);

This group of functions deals with JSON objects

char *json_to_string(struct json_object *obj);

enum json_type json_type(struct json_object *obj);

int json_equals(struct json_object *obj_1, struct json_object *obj_2);

This group consists of some helper functions.

2. JSON-RPC functions

For dealing with JSON-RPC uses two structures

• struct json_rpc; — to store information about all callbacks, incoming requests, and so on.
• struct json_rpc_request; — to represent incoming JSON-RPC request.

typedef void (*json_rpc_method)(struct json_rpc_request *req, struct json_object *obj, void *arg); — it is a type of JSON-RPC registered methods (callbacks in implementation).

typedef void (*json_rpc_result)(struct json_rpc *jr, struct json_object *obj, void *arg); — callbacks of this type are invoked after processing JSON-RPC response.

struct json_rpc *json_rpc_new();

void json_rpc_free(struct json_rpc *jr);

these function deals with main json_rpc structure

int json_rpc_add_method(struct json_rpc *jr, char *name, json_rpc_method method, void *arg);

void json_rpc_del_method(struct json_rpc *jr, char *name);

adding/removing registered callbacks that invoked by name from JSON-RPC requests

void json_rpc_return(struct json_rpc_request *jr, struct json_object *res); — this is only true way of return from registered callbacks

void json_rpc_process_request(struct json_rpc *jr, struct json_object *obj, json_rpc_result user_cb, void *cb_arg); — process request and call user_cb with cb_arg after completion processing request

int json_rpc_preprocess_request(struct json_rpc *jr, struct json_object *req, json_rpc_result res_cb, void *cb_arg); — this method allows to bind users res_cbwith id of request, and so thisres_cb` will be invoked after receiving response with same id.

void json_rpc_process_response(struct json_rpc *jr, struct json_object *resp);

int json_rpc_is_response(struct json_object *obj);

methods that deal with received JSON-RPC responses

3. JSON-RPC transport functions

LibJSONRPC has three out-of-the-box kinds of transport — TCP (maybe with TLS/SSL), HTTP (maybe HTTPS) and WebSocket.

struct json_rpc_tt; — structure, that saves information about chosen transport and linked json_rpc structure

struct json_rpc_tt *json_rpc_tt_ws_new(struct json_rpc *jr, struct ws_connection *conn, ws_error_cb e_cb, void *arg); — create json-rpc transport structure for web-socket connection

struct json_rpc_tt *json_rpc_tt_tcp_new(struct json_rpc *jr, struct bufevent *bufev, everrcb ecb, void *arg); — for TCP connection (via libevent0's bufevents)

struct json_rpc_tt *json_rpc_tt_http_new(struct json_rpc *jr, struct evhttp *eh, char *uri); — for HTTP connection (via libevent0's evhttp)

int json_rpc_tt_send(struct json_rpc_tt *jt, struct json_object *req, json_rpc_result res_cb, void *arg); — asynchronous sending of JSON-RPC request and invoking res_cb after receiving json-rpc response.

void json_rpc_tt_free(struct json_rpc_tt *jt); — destroys json_rpc_tt structure.