jsonrpc.h File Reference

JSON-RPC 2.0 server implementation. More...

Data Structures

struct  spdk_jsonrpc_client_response
 

Macros

#define SPDK_JSONRPC_ERROR_PARSE_ERROR   -32700
 
#define SPDK_JSONRPC_ERROR_INVALID_REQUEST   -32600
 
#define SPDK_JSONRPC_ERROR_METHOD_NOT_FOUND   -32601
 
#define SPDK_JSONRPC_ERROR_INVALID_PARAMS   -32602
 
#define SPDK_JSONRPC_ERROR_INTERNAL_ERROR   -32603
 
#define SPDK_JSONRPC_ERROR_INVALID_STATE   -1
 

Typedefs

typedef void(* spdk_jsonrpc_handle_request_fn) (struct spdk_jsonrpc_request *request, const struct spdk_json_val *method, const struct spdk_json_val *params)
 User callback to handle a single JSON-RPC request. More...
 
typedef void(* spdk_jsonrpc_conn_closed_fn) (struct spdk_jsonrpc_server_conn *conn, void *arg)
 
typedef int(* spdk_jsonrpc_client_response_parser) (void *parser_ctx, const struct spdk_json_val *result)
 Function for specific RPC method response parsing handlers. More...
 

Functions

struct spdk_jsonrpc_server * spdk_jsonrpc_server_listen (int domain, int protocol, struct sockaddr *listen_addr, socklen_t addrlen, spdk_jsonrpc_handle_request_fn handle_request)
 Create a JSON-RPC server listening on the required address. More...
 
int spdk_jsonrpc_server_poll (struct spdk_jsonrpc_server *server)
 Poll the requests to the JSON-RPC server. More...
 
void spdk_jsonrpc_server_shutdown (struct spdk_jsonrpc_server *server)
 Shutdown the JSON-RPC server. More...
 
struct spdk_jsonrpc_server_conn * spdk_jsonrpc_get_conn (struct spdk_jsonrpc_request *request)
 Return connection associated to request. More...
 
int spdk_jsonrpc_conn_add_close_cb (struct spdk_jsonrpc_server_conn *conn, spdk_jsonrpc_conn_closed_fn cb, void *ctx)
 Add callback called when connection is closed. More...
 
int spdk_jsonrpc_conn_del_close_cb (struct spdk_jsonrpc_server_conn *conn, spdk_jsonrpc_conn_closed_fn cb, void *ctx)
 Remove registered close callback. More...
 
struct spdk_json_write_ctx * spdk_jsonrpc_begin_result (struct spdk_jsonrpc_request *request)
 Begin building a response to a JSON-RPC request. More...
 
void spdk_jsonrpc_end_result (struct spdk_jsonrpc_request *request, struct spdk_json_write_ctx *w)
 Complete and send a JSON-RPC response. More...
 
void spdk_jsonrpc_send_error_response (struct spdk_jsonrpc_request *request, int error_code, const char *msg)
 Send an error response to a JSON-RPC request. More...
 
void spdk_jsonrpc_send_error_response_fmt (struct spdk_jsonrpc_request *request, int error_code, const char *fmt,...)
 Send an error response to a JSON-RPC request. More...
 
struct spdk_json_write_ctx * spdk_jsonrpc_begin_request (struct spdk_jsonrpc_client_request *request, int32_t id, const char *method)
 Begin building a JSON-RPC request. More...
 
void spdk_jsonrpc_end_request (struct spdk_jsonrpc_client_request *request, struct spdk_json_write_ctx *w)
 Complete a JSON-RPC request. More...
 
struct spdk_jsonrpc_client * spdk_jsonrpc_client_connect (const char *addr, int addr_family)
 Connect to the specified RPC server. More...
 
void spdk_jsonrpc_client_close (struct spdk_jsonrpc_client *client)
 Close JSON-RPC connection and free client object. More...
 
struct spdk_jsonrpc_client_request * spdk_jsonrpc_client_create_request (void)
 Create one JSON-RPC request. More...
 
void spdk_jsonrpc_client_free_request (struct spdk_jsonrpc_client_request *req)
 Free one JSON-RPC request. More...
 
int spdk_jsonrpc_client_send_request (struct spdk_jsonrpc_client *client, struct spdk_jsonrpc_client_request *req)
 Send the JSON-RPC request in JSON-RPC client. More...
 
int spdk_jsonrpc_client_poll (struct spdk_jsonrpc_client *client, int timeout)
 Poll the JSON-RPC client. More...
 
struct spdk_jsonrpc_client_responsespdk_jsonrpc_client_get_response (struct spdk_jsonrpc_client *client)
 Return JSON RPC response object representing next available response from client connection. More...
 
void spdk_jsonrpc_client_free_response (struct spdk_jsonrpc_client_response *resp)
 Free response object obtained from spdk_jsonrpc_client_get_response. More...
 

Detailed Description

JSON-RPC 2.0 server implementation.

Typedef Documentation

◆ spdk_jsonrpc_client_response_parser

typedef int(* spdk_jsonrpc_client_response_parser) (void *parser_ctx, const struct spdk_json_val *result)

Function for specific RPC method response parsing handlers.

Parameters
parser_ctxcontext where analysis are put.
resultjson values responsed to this method.
Returns
0 on success. SPDK_JSON_PARSE_INVALID on failure.

◆ spdk_jsonrpc_handle_request_fn

typedef void(* spdk_jsonrpc_handle_request_fn) (struct spdk_jsonrpc_request *request, const struct spdk_json_val *method, const struct spdk_json_val *params)

User callback to handle a single JSON-RPC request.

The user should respond by calling one of spdk_jsonrpc_begin_result() or spdk_jsonrpc_send_error_response().

Parameters
requestJSON-RPC request to handle.
methodFunction to handle the request.
paramParameters passed to the function 'method'.

Function Documentation

◆ spdk_jsonrpc_begin_request()

struct spdk_json_write_ctx* spdk_jsonrpc_begin_request ( struct spdk_jsonrpc_client_request *  request,
int32_t  id,
const char *  method 
)

Begin building a JSON-RPC request.

If this function returns non-NULL, the user must call spdk_jsonrpc_end_request() on the request after writing the desired request object to the spdk_json_write_ctx.

Parameters
requestJSON-RPC request.
idID index for the request. If < 0 skip ID.
methodName of the RPC method. If NULL caller will have to create "method" key.
Returns
JSON write context or NULL in case of error.

◆ spdk_jsonrpc_begin_result()

struct spdk_json_write_ctx* spdk_jsonrpc_begin_result ( struct spdk_jsonrpc_request *  request)

Begin building a response to a JSON-RPC request.

If this function returns non-NULL, the user must call spdk_jsonrpc_end_result() on the request after writing the desired response object to the spdk_json_write_ctx.

Parameters
requestJSON-RPC request to respond to.
Returns
Non-NULL pointer to JSON write context to write the response object to.

◆ spdk_jsonrpc_client_close()

void spdk_jsonrpc_client_close ( struct spdk_jsonrpc_client *  client)

Close JSON-RPC connection and free client object.

This function is not thread safe and should only be called from one thread at a time while no other threads are actively client object.

Parameters
clientJSON-RPC client.

◆ spdk_jsonrpc_client_connect()

struct spdk_jsonrpc_client* spdk_jsonrpc_client_connect ( const char *  addr,
int  addr_family 
)

Connect to the specified RPC server.

Parameters
addrRPC socket address.
addr_familyProtocol families of address.
Returns
JSON-RPC client on success, NULL on failure and errno set to indicate the cause of the error.

◆ spdk_jsonrpc_client_create_request()

struct spdk_jsonrpc_client_request* spdk_jsonrpc_client_create_request ( void  )

Create one JSON-RPC request.

Returned request must be passed to spdk_jsonrpc_client_send_request when done or to spdk_jsonrpc_client_free_request if discaded.

Returns
pointer to JSON-RPC request object.

◆ spdk_jsonrpc_client_free_request()

void spdk_jsonrpc_client_free_request ( struct spdk_jsonrpc_client_request *  req)

Free one JSON-RPC request.

Parameters
reqpointer to JSON-RPC request object.

◆ spdk_jsonrpc_client_free_response()

void spdk_jsonrpc_client_free_response ( struct spdk_jsonrpc_client_response resp)

Free response object obtained from spdk_jsonrpc_client_get_response.

Parameters
resppointer to JSON RPC response object. If NULL no operation is performed.

◆ spdk_jsonrpc_client_get_response()

struct spdk_jsonrpc_client_response* spdk_jsonrpc_client_get_response ( struct spdk_jsonrpc_client *  client)

Return JSON RPC response object representing next available response from client connection.

Returned pointer must be freed using spdk_jsonrpc_client_free_response

This function is not thread safe and should only be called from one thread at a time while no other threads are actively client object.

Parameters
client
Returns
pointer to JSON RPC response object or NULL if no response available.

◆ spdk_jsonrpc_client_poll()

int spdk_jsonrpc_client_poll ( struct spdk_jsonrpc_client *  client,
int  timeout 
)

Poll the JSON-RPC client.

When any response is available use spdk_jsonrpc_client_get_response to retrieve it.

This function is not thread safe and should only be called from one thread at a time while no other threads are actively client object.

Parameters
clientJSON-RPC client.
timeoutTime in miliseconds this function will block. -1 block forever, 0 don't block.
Returns
If no error occurred, this function returns a non-negative number indicating how many ready responses can be retrieved. If an error occurred, this function returns one of the following negated errno values: -ENOTCONN - not connected yet. Try again later. -EINVAL - response is detected to be invalid. Client connection should be terminated. -ENOSPC - no space to receive another response. User need to retrieve waiting responses. -EIO - connection terminated (or other critical error). Client connection should be terminated. -ENOMEM - out of memory

◆ spdk_jsonrpc_client_send_request()

int spdk_jsonrpc_client_send_request ( struct spdk_jsonrpc_client *  client,
struct spdk_jsonrpc_client_request *  req 
)

Send the JSON-RPC request in JSON-RPC client.

Library takes ownership of the request object and will free it when done.

This function is not thread safe and should only be called from one thread at a time while no other threads are actively client object.

Parameters
clientJSON-RPC client.
reqJSON-RPC request.
Returns
0 on success or negative error code. -ENOSPC - no space left to queue another request. Try again later.

◆ spdk_jsonrpc_conn_add_close_cb()

int spdk_jsonrpc_conn_add_close_cb ( struct spdk_jsonrpc_server_conn *  conn,
spdk_jsonrpc_conn_closed_fn  cb,
void *  ctx 
)

Add callback called when connection is closed.

Pair of cb and ctx must be unique or error is returned. Registered callback is called only once and there is no need to call spdk_jsonrpc_conn_del_close_cb inside from cb.

Note
Current implementation allow only one close callback per connection.
Parameters
connJSON RPC server connection
cbcalback function
ctxargument for cb
Returns
0 on success, or negated errno code: -EEXIST cb and ctx is already registered -ENOTCONN Callback can't be added because connection is closed. -ENOSPC no more space to register callback.

◆ spdk_jsonrpc_conn_del_close_cb()

int spdk_jsonrpc_conn_del_close_cb ( struct spdk_jsonrpc_server_conn *  conn,
spdk_jsonrpc_conn_closed_fn  cb,
void *  ctx 
)

Remove registered close callback.

Parameters
connJSON RPC server connection
cbcalback function
ctxargument for cb
Returns
0 on success, or negated errno code: -ENOENT cb and ctx pair is not registered

◆ spdk_jsonrpc_end_request()

void spdk_jsonrpc_end_request ( struct spdk_jsonrpc_client_request *  request,
struct spdk_json_write_ctx *  w 
)

Complete a JSON-RPC request.

Parameters
requestJSON-RPC request.
wJSON write context returned from spdk_jsonrpc_begin_request().

◆ spdk_jsonrpc_end_result()

void spdk_jsonrpc_end_result ( struct spdk_jsonrpc_request *  request,
struct spdk_json_write_ctx *  w 
)

Complete and send a JSON-RPC response.

Parameters
requestRequest to complete the response for.
wJSON write context returned from spdk_jsonrpc_begin_result().

◆ spdk_jsonrpc_get_conn()

struct spdk_jsonrpc_server_conn* spdk_jsonrpc_get_conn ( struct spdk_jsonrpc_request *  request)

Return connection associated to request.

Parameters
requestJSON-RPC request
Returns
JSON RPC server connection

◆ spdk_jsonrpc_send_error_response()

void spdk_jsonrpc_send_error_response ( struct spdk_jsonrpc_request *  request,
int  error_code,
const char *  msg 
)

Send an error response to a JSON-RPC request.

This is shorthand for spdk_jsonrpc_begin_result() + spdk_jsonrpc_end_result() with an error object.

Parameters
requestJSON-RPC request to respond to.
error_codeInteger error code to return (may be one of the SPDK_JSONRPC_ERROR_ errors, or a custom error code).
msgString error message to return.

◆ spdk_jsonrpc_send_error_response_fmt()

void spdk_jsonrpc_send_error_response_fmt ( struct spdk_jsonrpc_request *  request,
int  error_code,
const char *  fmt,
  ... 
)

Send an error response to a JSON-RPC request.

This is shorthand for printf() + spdk_jsonrpc_send_error_response().

Parameters
requestJSON-RPC request to respond to.
error_codeInteger error code to return (may be one of the SPDK_JSONRPC_ERROR_ errors, or a custom error code).
fmtPrintf-like format string.

◆ spdk_jsonrpc_server_listen()

struct spdk_jsonrpc_server* spdk_jsonrpc_server_listen ( int  domain,
int  protocol,
struct sockaddr *  listen_addr,
socklen_t  addrlen,
spdk_jsonrpc_handle_request_fn  handle_request 
)

Create a JSON-RPC server listening on the required address.

Parameters
domainSocket family.
protocolProtocol.
listen_addrListening address.
addrlenLength of address.
handle_requestUser callback to handle a JSON-RPC request.
Returns
a pointer to the JSON-RPC server.

◆ spdk_jsonrpc_server_poll()

int spdk_jsonrpc_server_poll ( struct spdk_jsonrpc_server *  server)

Poll the requests to the JSON-RPC server.

This function does accept, receive, handle the requests and reply to them.

Parameters
serverJSON-RPC server.
Returns
0 on success.

◆ spdk_jsonrpc_server_shutdown()

void spdk_jsonrpc_server_shutdown ( struct spdk_jsonrpc_server *  server)

Shutdown the JSON-RPC server.

Parameters
serverJSON-RPC server.