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.

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.

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.

int	spdk_jsonrpc_server_poll (struct spdk_jsonrpc_server *server)
	Poll the requests to the JSON-RPC server.

void	spdk_jsonrpc_server_shutdown (struct spdk_jsonrpc_server *server)
	Shutdown the JSON-RPC server.

struct spdk_jsonrpc_server_conn *	spdk_jsonrpc_get_conn (struct spdk_jsonrpc_request *request)
	Return connection associated to `request`.

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.

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.

struct spdk_json_write_ctx *	spdk_jsonrpc_begin_result (struct spdk_jsonrpc_request *request)
	Begin building a response to a JSON-RPC request.

void	spdk_jsonrpc_end_result (struct spdk_jsonrpc_request request, struct spdk_json_write_ctx w)
	Complete and send a JSON-RPC response.

void	spdk_jsonrpc_send_bool_response (struct spdk_jsonrpc_request *request, bool value)
	Complete a JSON-RPC response and write bool result.

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.

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.

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.

void	spdk_jsonrpc_end_request (struct spdk_jsonrpc_client_request request, struct spdk_json_write_ctx w)
	Complete a JSON-RPC request.

struct spdk_jsonrpc_client *	spdk_jsonrpc_client_connect (const char *addr, int addr_family)
	Connect to the specified RPC server.

void	spdk_jsonrpc_client_close (struct spdk_jsonrpc_client *client)
	Close JSON-RPC connection and free `client` object.

struct spdk_jsonrpc_client_request *	spdk_jsonrpc_client_create_request (void)
	Create one JSON-RPC request.

void	spdk_jsonrpc_client_free_request (struct spdk_jsonrpc_client_request *req)
	Free one JSON-RPC 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.

int	spdk_jsonrpc_client_poll (struct spdk_jsonrpc_client *client, int timeout)
	Poll the JSON-RPC client.

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.

void	spdk_jsonrpc_client_free_response (struct spdk_jsonrpc_client_response *resp)
	Free response object obtained from `spdk_jsonrpc_client_get_response`.

void	spdk_jsonrpc_set_log_level (enum spdk_log_level level)
	Set the log level used by the JSON-RPC server to log RPC request and response objects.

void	spdk_jsonrpc_set_log_file (FILE *file)
	Set the log file used by the JSON-RPC server to log RPC request and response objects.

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_ctx	context where analysis are put.
result	json values responded 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

request	JSON-RPC request to handle.
method	Function to handle the request.
params	Parameters 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

request	JSON-RPC request.
id	ID index for the request. If < 0 skip ID.
method	Name 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

request JSON-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

client JSON-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

addr	RPC socket address.
addr_family	Protocol 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

req	pointer 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

resp	pointer 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

client	JSON-RPC client.
timeout	Time in milliseconds 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

client	JSON-RPC client.
req	JSON-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

conn	JSON RPC server connection
cb	callback function
ctx	argument 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

conn	JSON RPC server connection
cb	callback function
ctx	argument 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

request	JSON-RPC request.
w	JSON 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

request	Request to complete the response for.
w	JSON 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

request JSON-RPC request

Returns: JSON RPC server connection

◆ spdk_jsonrpc_send_bool_response()

void spdk_jsonrpc_send_bool_response	(	struct spdk_jsonrpc_request *	request,
		bool	value )

Complete a JSON-RPC response and write bool result.

Parameters

request	Request to complete the response for.
value	Write bool result value.

◆ 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

request	JSON-RPC request to respond to.
error_code	Integer error code to return (may be one of the SPDK_JSONRPC_ERROR_ errors, or a custom error code).
msg	String 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

request	JSON-RPC request to respond to.
error_code	Integer error code to return (may be one of the SPDK_JSONRPC_ERROR_ errors, or a custom error code).
fmt	Printf-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

domain	Socket family.
protocol	Protocol.
listen_addr	Listening address.
addrlen	Length of address.
handle_request	User 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

server JSON-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

server JSON-RPC server.

◆ spdk_jsonrpc_set_log_file()

void spdk_jsonrpc_set_log_file ( FILE * file )

Set the log file used by the JSON-RPC server to log RPC request and response objects.

NOTE: This function should be called only before starting the JSON-RPC server.

Parameters

file	Log file pointer used to log RPC objects.

◆ spdk_jsonrpc_set_log_level()

void spdk_jsonrpc_set_log_level ( enum spdk_log_level level )

Set the log level used by the JSON-RPC server to log RPC request and response objects.

NOTE: This function should be called only before starting the JSON-RPC server. Users should set the level set by this function higher than the level set by spdk_log_set_print_level() or spdk_log_set_level().

Parameters

level Log level used to log RPC objects.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ spdk_jsonrpc_client_response_parser

◆ spdk_jsonrpc_handle_request_fn

Function Documentation

◆ spdk_jsonrpc_begin_request()

◆ spdk_jsonrpc_begin_result()

◆ spdk_jsonrpc_client_close()

◆ spdk_jsonrpc_client_connect()

◆ spdk_jsonrpc_client_create_request()

◆ spdk_jsonrpc_client_free_request()

◆ spdk_jsonrpc_client_free_response()

◆ spdk_jsonrpc_client_get_response()

◆ spdk_jsonrpc_client_poll()

◆ spdk_jsonrpc_client_send_request()

◆ spdk_jsonrpc_conn_add_close_cb()

◆ spdk_jsonrpc_conn_del_close_cb()

◆ spdk_jsonrpc_end_request()

◆ spdk_jsonrpc_end_result()

◆ spdk_jsonrpc_get_conn()

◆ spdk_jsonrpc_send_bool_response()

◆ spdk_jsonrpc_send_error_response()

◆ spdk_jsonrpc_send_error_response_fmt()

◆ spdk_jsonrpc_server_listen()

◆ spdk_jsonrpc_server_poll()

◆ spdk_jsonrpc_server_shutdown()

◆ spdk_jsonrpc_set_log_file()

◆ spdk_jsonrpc_set_log_level()