[ceph.git] / ceph / src / spdk / include / spdk / jsonrpc.h

/*-
 *   BSD LICENSE
 *
 *   Copyright (c) Intel Corporation.
 *   All rights reserved.
 *
 *   Redistribution and use in source and binary forms, with or without
 *   modification, are permitted provided that the following conditions
 *   are met:
 *
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in
 *       the documentation and/or other materials provided with the
 *       distribution.
 *     * Neither the name of Intel Corporation nor the names of its
 *       contributors may be used to endorse or promote products derived
 *       from this software without specific prior written permission.
 *
 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * \file
 * JSON-RPC 2.0 server implementation
 */

#ifndef SPDK_JSONRPC_H_
#define SPDK_JSONRPC_H_

#include "spdk/stdinc.h"

#include "spdk/json.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Defined error codes in JSON-RPC specification 2.0 */
#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

/* Custom error codes in SPDK

 * Error codes from and including -32768 to -32000 are reserved for
 * predefined errors, hence custom error codes must be outside of the range.
 */
#define SPDK_JSONRPC_ERROR_INVALID_STATE	-1

struct spdk_jsonrpc_server;
struct spdk_jsonrpc_request;

struct spdk_jsonrpc_client;
struct spdk_jsonrpc_client_request;

struct spdk_jsonrpc_client_response {
	struct spdk_json_val *version;
	struct spdk_json_val *id;
	struct spdk_json_val *result;
	struct spdk_json_val *error;
};

/**
 * 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().
 *
 * \param request JSON-RPC request to handle.
 * \param method Function to handle the request.
 * \param param Parameters passed to the function 'method'.
 */
typedef void (*spdk_jsonrpc_handle_request_fn)(
	struct spdk_jsonrpc_request *request,
	const struct spdk_json_val *method,
	const struct spdk_json_val *params);

struct spdk_jsonrpc_server_conn;

typedef void (*spdk_jsonrpc_conn_closed_fn)(struct spdk_jsonrpc_server_conn *conn, void *arg);

/**
 * Function for specific RPC method response parsing handlers.
 *
 * \param parser_ctx context where analysis are put.
 * \param result json values responsed to this method.
 *
 * \return 0 on success.
 *         SPDK_JSON_PARSE_INVALID on failure.
 */
typedef int (*spdk_jsonrpc_client_response_parser)(
	void *parser_ctx,
	const struct spdk_json_val *result);

/**
 * Create a JSON-RPC server listening on the required address.
 *
 * \param domain Socket family.
 * \param protocol Protocol.
 * \param listen_addr Listening address.
 * \param addrlen Length of address.
 * \param handle_request User callback to handle a JSON-RPC request.
 *
 * \return a pointer to the JSON-RPC server.
 */
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);

/**
 * Poll the requests to the JSON-RPC server.
 *
 * This function does accept, receive, handle the requests and reply to them.
 *
 * \param server JSON-RPC server.
 *
 * \return 0 on success.
 */
int spdk_jsonrpc_server_poll(struct spdk_jsonrpc_server *server);

/**
 * Shutdown the JSON-RPC server.
 *
 * \param server JSON-RPC server.
 */
void spdk_jsonrpc_server_shutdown(struct spdk_jsonrpc_server *server);

/**
 * Return connection associated to \c request
 *
 * \param request JSON-RPC request
 * \return JSON RPC server connection
 */
struct spdk_jsonrpc_server_conn *spdk_jsonrpc_get_conn(struct spdk_jsonrpc_request *request);

/**
 * Add callback called when connection is closed. Pair of  \c cb and \c ctx must be unique or error is returned.
 * Registered callback is called only once and there is no need to call  \c spdk_jsonrpc_conn_del_close_cb
 * inside from \c cb.
 *
 * \note Current implementation allow only one close callback per connection.
 *
 * \param conn JSON RPC server connection
 * \param cb calback function
 * \param ctx argument for \c cb
 *
 * \return 0 on success, or negated errno code:
 *  -EEXIST \c cb and \c ctx is already registered
 *  -ENOTCONN Callback can't be added because connection is closed.
 *  -ENOSPC no more space to register callback.
 */
int spdk_jsonrpc_conn_add_close_cb(struct spdk_jsonrpc_server_conn *conn,
				   spdk_jsonrpc_conn_closed_fn cb, void *ctx);

/**
 * Remove registered close callback.
 *
 * \param conn JSON RPC server connection
 * \param cb calback function
 * \param ctx argument for \c cb
 *
 * \return 0 on success, or negated errno code:
 *  -ENOENT \c cb and \c ctx pair is not registered
 */
int spdk_jsonrpc_conn_del_close_cb(struct spdk_jsonrpc_server_conn *conn,
				   spdk_jsonrpc_conn_closed_fn cb, void *ctx);

/**
 * 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.
 *
 * \param request JSON-RPC request to respond to.

 * \return Non-NULL pointer to JSON write context to write the response object to.
 */
struct spdk_json_write_ctx *spdk_jsonrpc_begin_result(struct spdk_jsonrpc_request *request);

/**
 * Complete and send a JSON-RPC response.
 *
 * \param request Request to complete the response for.
 * \param w JSON write context returned from spdk_jsonrpc_begin_result().
 */
void spdk_jsonrpc_end_result(struct spdk_jsonrpc_request *request, struct spdk_json_write_ctx *w);

/**
 * 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.
 *
 * \param request JSON-RPC request to respond to.
 * \param error_code Integer error code to return (may be one of the
 * SPDK_JSONRPC_ERROR_ errors, or a custom error code).
 * \param msg String error message to return.
 */
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 printf() + spdk_jsonrpc_send_error_response().
 *
 * \param request JSON-RPC request to respond to.
 * \param error_code Integer error code to return (may be one of the
 * SPDK_JSONRPC_ERROR_ errors, or a custom error code).
 * \param fmt Printf-like format string.
 */
void spdk_jsonrpc_send_error_response_fmt(struct spdk_jsonrpc_request *request,
		int error_code, const char *fmt, ...) __attribute__((format(printf, 3, 4)));

/**
 * 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.
 *
 * \param request JSON-RPC request.
 * \param id ID index for the request. If < 0 skip ID.
 * \param method Name of the RPC method. If NULL caller will have to create "method" key.
 *
 * \return JSON write context or NULL in case of error.
 */
struct spdk_json_write_ctx *
spdk_jsonrpc_begin_request(struct spdk_jsonrpc_client_request *request, int32_t id,
			   const char *method);

/**
 * Complete a JSON-RPC request.
 *
 * \param request JSON-RPC request.
 * \param w JSON write context returned from spdk_jsonrpc_begin_request().
 */
void spdk_jsonrpc_end_request(struct spdk_jsonrpc_client_request *request,
			      struct spdk_json_write_ctx *w);

/**
 * Connect to the specified RPC server.
 *
 * \param addr RPC socket address.
 * \param addr_family Protocol families of address.
 *
 * \return JSON-RPC client on success, NULL on failure and errno set to indicate
 * the cause of the error.
 */
struct spdk_jsonrpc_client *spdk_jsonrpc_client_connect(const char *addr, int addr_family);

/**
 * Close JSON-RPC connection and free \c 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 \c client object.
 *
 * \param client JSON-RPC client.
 */
void spdk_jsonrpc_client_close(struct spdk_jsonrpc_client *client);

/**
 * Create one JSON-RPC request. Returned request must be passed to
 * \c spdk_jsonrpc_client_send_request when done or to \c spdk_jsonrpc_client_free_request
 * if discaded.
 *
 * \return pointer to JSON-RPC request object.
 */
struct spdk_jsonrpc_client_request *spdk_jsonrpc_client_create_request(void);

/**
 * Free one JSON-RPC request.
 *
 * \param req pointer to JSON-RPC request object.
 */
void spdk_jsonrpc_client_free_request(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 \c client object.
 *
 * \param client JSON-RPC client.
 * \param req JSON-RPC request.
 *
 * \return 0 on success or negative error code.
 * -ENOSPC - no space left to queue another request. Try again later.
 */
int spdk_jsonrpc_client_send_request(struct spdk_jsonrpc_client *client,
				     struct spdk_jsonrpc_client_request *req);

/**
 * Poll the JSON-RPC client. When any response is available use
 * \c 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 \c client object.
 *
 * \param client JSON-RPC client.
 * \param timeout Time in miliseconds this function will block. -1 block forever, 0 don't block.
 *
 * \return 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
 */
int spdk_jsonrpc_client_poll(struct spdk_jsonrpc_client *client, int timeout);

/**
 * Return JSON RPC response object representing next available response from client connection.
 * Returned pointer must be freed using \c 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 \c client object.
 *
 * \param client
 * \return pointer to JSON RPC response object or NULL if no response available.
 */
struct spdk_jsonrpc_client_response *spdk_jsonrpc_client_get_response(struct spdk_jsonrpc_client
		*client);

/**
 * Free response object obtained from \c spdk_jsonrpc_client_get_response
 *
 * \param resp pointer to JSON RPC response object. If NULL no operation is performed.
 */
void spdk_jsonrpc_client_free_response(struct spdk_jsonrpc_client_response *resp);


#ifdef __cplusplus
}
#endif

#endif
Commit	Line	Data
7c673cae FG	1	/*-
	2	* BSD LICENSE
	3	*
	4	* Copyright (c) Intel Corporation.
	5	* All rights reserved.
	6	*
	7	* Redistribution and use in source and binary forms, with or without
	8	* modification, are permitted provided that the following conditions
	9	* are met:
	10	*
	11	* * Redistributions of source code must retain the above copyright
	12	* notice, this list of conditions and the following disclaimer.
	13	* * Redistributions in binary form must reproduce the above copyright
	14	* notice, this list of conditions and the following disclaimer in
	15	* the documentation and/or other materials provided with the
	16	* distribution.
	17	* * Neither the name of Intel Corporation nor the names of its
	18	* contributors may be used to endorse or promote products derived
	19	* from this software without specific prior written permission.
	20	*
	21	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
	22	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	23	* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
	24	* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
	25	* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	26	* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	27	* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	28	* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	29	* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	30	* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
	31	* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	32	*/
	33
	34	/**
	35	* \file
	36	* JSON-RPC 2.0 server implementation
	37	*/
	38
	39	#ifndef SPDK_JSONRPC_H_
	40	#define SPDK_JSONRPC_H_
	41
11fdf7f2	42	#include "spdk/stdinc.h"
7c673cae	43
11fdf7f2	44	#include "spdk/json.h"
7c673cae	45
11fdf7f2 TL	46	#ifdef __cplusplus
	47	extern "C" {
	48	#endif
7c673cae	49
11fdf7f2	50	/* Defined error codes in JSON-RPC specification 2.0 */
7c673cae FG	51	#define SPDK_JSONRPC_ERROR_PARSE_ERROR -32700
	52	#define SPDK_JSONRPC_ERROR_INVALID_REQUEST -32600
	53	#define SPDK_JSONRPC_ERROR_METHOD_NOT_FOUND -32601
	54	#define SPDK_JSONRPC_ERROR_INVALID_PARAMS -32602
	55	#define SPDK_JSONRPC_ERROR_INTERNAL_ERROR -32603
	56
11fdf7f2 TL	57	/* Custom error codes in SPDK
	58
	59	* Error codes from and including -32768 to -32000 are reserved for
	60	* predefined errors, hence custom error codes must be outside of the range.
	61	*/
	62	#define SPDK_JSONRPC_ERROR_INVALID_STATE -1
	63
7c673cae	64	struct spdk_jsonrpc_server;
11fdf7f2 TL	65	struct spdk_jsonrpc_request;
	66
	67	struct spdk_jsonrpc_client;
	68	struct spdk_jsonrpc_client_request;
7c673cae	69
9f95a23c TL	70	struct spdk_jsonrpc_client_response {
	71	struct spdk_json_val *version;
	72	struct spdk_json_val *id;
	73	struct spdk_json_val *result;
	74	struct spdk_json_val *error;
	75	};
	76
7c673cae FG	77	/**
	78	* User callback to handle a single JSON-RPC request.
	79	*
	80	* The user should respond by calling one of spdk_jsonrpc_begin_result() or
11fdf7f2 TL	81	* spdk_jsonrpc_send_error_response().
	82	*
	83	* \param request JSON-RPC request to handle.
	84	* \param method Function to handle the request.
	85	* \param param Parameters passed to the function 'method'.
7c673cae FG	86	*/
7c673cae FG	87	typedef void (*spdk_jsonrpc_handle_request_fn)(
11fdf7f2	88	struct spdk_jsonrpc_request *request,
7c673cae	89	const struct spdk_json_val *method,
11fdf7f2	90	const struct spdk_json_val *params);
7c673cae	91
9f95a23c TL	92	struct spdk_jsonrpc_server_conn;
	93
	94	typedef void (spdk_jsonrpc_conn_closed_fn)(struct spdk_jsonrpc_server_conn conn, void *arg);
	95
11fdf7f2 TL	96	/**
	97	* Function for specific RPC method response parsing handlers.
	98	*
	99	* \param parser_ctx context where analysis are put.
	100	* \param result json values responsed to this method.
	101	*
	102	* \return 0 on success.
	103	* SPDK_JSON_PARSE_INVALID on failure.
	104	*/
	105	typedef int (*spdk_jsonrpc_client_response_parser)(
	106	void *parser_ctx,
	107	const struct spdk_json_val *result);
	108
	109	/**
	110	* Create a JSON-RPC server listening on the required address.
	111	*
	112	* \param domain Socket family.
	113	* \param protocol Protocol.
	114	* \param listen_addr Listening address.
	115	* \param addrlen Length of address.
	116	* \param handle_request User callback to handle a JSON-RPC request.
	117	*
	118	* \return a pointer to the JSON-RPC server.
	119	*/
7c673cae FG	120	struct spdk_jsonrpc_server *spdk_jsonrpc_server_listen(int domain, int protocol,
	121	struct sockaddr *listen_addr, socklen_t addrlen, spdk_jsonrpc_handle_request_fn handle_request);
	122
11fdf7f2 TL	123	/**
	124	* Poll the requests to the JSON-RPC server.
	125	*
	126	* This function does accept, receive, handle the requests and reply to them.
	127	*
	128	* \param server JSON-RPC server.
	129	*
	130	* \return 0 on success.
	131	*/
7c673cae FG	132	int spdk_jsonrpc_server_poll(struct spdk_jsonrpc_server *server);
7c673cae FG	133
11fdf7f2 TL	134	/**
	135	* Shutdown the JSON-RPC server.
	136	*
	137	* \param server JSON-RPC server.
	138	*/
7c673cae FG	139	void spdk_jsonrpc_server_shutdown(struct spdk_jsonrpc_server *server);
7c673cae FG	140
9f95a23c TL	141	/**
	142	* Return connection associated to \c request
	143	*
	144	* \param request JSON-RPC request
	145	* \return JSON RPC server connection
	146	*/
	147	struct spdk_jsonrpc_server_conn spdk_jsonrpc_get_conn(struct spdk_jsonrpc_request request);
	148
	149	/**
	150	* Add callback called when connection is closed. Pair of \c cb and \c ctx must be unique or error is returned.
	151	* Registered callback is called only once and there is no need to call \c spdk_jsonrpc_conn_del_close_cb
	152	* inside from \c cb.
	153	*
	154	* \note Current implementation allow only one close callback per connection.
	155	*
	156	* \param conn JSON RPC server connection
	157	* \param cb calback function
	158	* \param ctx argument for \c cb
	159	*
	160	* \return 0 on success, or negated errno code:
	161	* -EEXIST \c cb and \c ctx is already registered
	162	* -ENOTCONN Callback can't be added because connection is closed.
	163	* -ENOSPC no more space to register callback.
	164	*/
	165	int spdk_jsonrpc_conn_add_close_cb(struct spdk_jsonrpc_server_conn *conn,
	166	spdk_jsonrpc_conn_closed_fn cb, void *ctx);
	167
	168	/**
	169	* Remove registered close callback.
	170	*
	171	* \param conn JSON RPC server connection
	172	* \param cb calback function
	173	* \param ctx argument for \c cb
	174	*
	175	* \return 0 on success, or negated errno code:
	176	* -ENOENT \c cb and \c ctx pair is not registered
	177	*/
	178	int spdk_jsonrpc_conn_del_close_cb(struct spdk_jsonrpc_server_conn *conn,
	179	spdk_jsonrpc_conn_closed_fn cb, void *ctx);
	180
11fdf7f2 TL	181	/**
	182	* Begin building a response to a JSON-RPC request.
	183	*
	184	* If this function returns non-NULL, the user must call spdk_jsonrpc_end_result()
	185	* on the request after writing the desired response object to the spdk_json_write_ctx.
	186	*
	187	* \param request JSON-RPC request to respond to.
	188
f67539c2	189	* \return Non-NULL pointer to JSON write context to write the response object to.
11fdf7f2 TL	190	*/
	191	struct spdk_json_write_ctx spdk_jsonrpc_begin_result(struct spdk_jsonrpc_request request);
	192
	193	/**
	194	* Complete and send a JSON-RPC response.
	195	*
	196	* \param request Request to complete the response for.
	197	* \param w JSON write context returned from spdk_jsonrpc_begin_result().
	198	*/
	199	void spdk_jsonrpc_end_result(struct spdk_jsonrpc_request request, struct spdk_json_write_ctx w);
	200
	201	/**
	202	* Send an error response to a JSON-RPC request.
	203	*
	204	* This is shorthand for spdk_jsonrpc_begin_result() + spdk_jsonrpc_end_result()
	205	* with an error object.
	206	*
	207	* \param request JSON-RPC request to respond to.
	208	* \param error_code Integer error code to return (may be one of the
	209	* SPDK_JSONRPC_ERROR_ errors, or a custom error code).
	210	* \param msg String error message to return.
	211	*/
	212	void spdk_jsonrpc_send_error_response(struct spdk_jsonrpc_request *request,
	213	int error_code, const char *msg);
	214
	215	/**
	216	* Send an error response to a JSON-RPC request.
	217	*
	218	* This is shorthand for printf() + spdk_jsonrpc_send_error_response().
	219	*
	220	* \param request JSON-RPC request to respond to.
	221	* \param error_code Integer error code to return (may be one of the
	222	* SPDK_JSONRPC_ERROR_ errors, or a custom error code).
	223	* \param fmt Printf-like format string.
	224	*/
	225	void spdk_jsonrpc_send_error_response_fmt(struct spdk_jsonrpc_request *request,
	226	int error_code, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
	227
	228	/**
	229	* Begin building a JSON-RPC request.
	230	*
	231	* If this function returns non-NULL, the user must call spdk_jsonrpc_end_request()
	232	* on the request after writing the desired request object to the spdk_json_write_ctx.
	233	*
	234	* \param request JSON-RPC request.
	235	* \param id ID index for the request. If < 0 skip ID.
	236	* \param method Name of the RPC method. If NULL caller will have to create "method" key.
	237	*
9f95a23c	238	* \return JSON write context or NULL in case of error.
11fdf7f2 TL	239	*/
	240	struct spdk_json_write_ctx *
	241	spdk_jsonrpc_begin_request(struct spdk_jsonrpc_client_request *request, int32_t id,
	242	const char *method);
7c673cae	243
11fdf7f2 TL	244	/**
	245	* Complete a JSON-RPC request.
	246	*
	247	* \param request JSON-RPC request.
	248	* \param w JSON write context returned from spdk_jsonrpc_begin_request().
	249	*/
	250	void spdk_jsonrpc_end_request(struct spdk_jsonrpc_client_request *request,
	251	struct spdk_json_write_ctx *w);
	252
	253	/**
	254	* Connect to the specified RPC server.
	255	*
9f95a23c	256	* \param addr RPC socket address.
11fdf7f2 TL	257	* \param addr_family Protocol families of address.
11fdf7f2 TL	258	*
9f95a23c TL	259	* \return JSON-RPC client on success, NULL on failure and errno set to indicate
9f95a23c TL	260	* the cause of the error.
11fdf7f2	261	*/
9f95a23c	262	struct spdk_jsonrpc_client spdk_jsonrpc_client_connect(const char addr, int addr_family);
11fdf7f2 TL	263
11fdf7f2 TL	264	/**
9f95a23c TL	265	* Close JSON-RPC connection and free \c client object.
	266	*
	267	* This function is not thread safe and should only be called from one thread at
	268	* a time while no other threads are actively \c client object.
11fdf7f2 TL	269	*
	270	* \param client JSON-RPC client.
	271	*/
	272	void spdk_jsonrpc_client_close(struct spdk_jsonrpc_client *client);
	273
	274	/**
9f95a23c TL	275	* Create one JSON-RPC request. Returned request must be passed to
	276	* \c spdk_jsonrpc_client_send_request when done or to \c spdk_jsonrpc_client_free_request
	277	* if discaded.
11fdf7f2	278	*
9f95a23c	279	* \return pointer to JSON-RPC request object.
11fdf7f2 TL	280	*/
	281	struct spdk_jsonrpc_client_request *spdk_jsonrpc_client_create_request(void);
	282
	283	/**
9f95a23c	284	* Free one JSON-RPC request.
11fdf7f2	285	*
9f95a23c	286	* \param req pointer to JSON-RPC request object.
11fdf7f2	287	*/
9f95a23c	288	void spdk_jsonrpc_client_free_request(struct spdk_jsonrpc_client_request *req);
11fdf7f2 TL	289
11fdf7f2 TL	290	/**
9f95a23c TL	291	* Send the JSON-RPC request in JSON-RPC client. Library takes ownership of the
	292	* request object and will free it when done.
	293	*
	294	* This function is not thread safe and should only be called from one thread at
	295	* a time while no other threads are actively \c client object.
11fdf7f2 TL	296	*
	297	* \param client JSON-RPC client.
	298	* \param req JSON-RPC request.
	299	*
9f95a23c TL	300	* \return 0 on success or negative error code.
9f95a23c TL	301	* -ENOSPC - no space left to queue another request. Try again later.
11fdf7f2 TL	302	*/
	303	int spdk_jsonrpc_client_send_request(struct spdk_jsonrpc_client *client,
	304	struct spdk_jsonrpc_client_request *req);
	305
	306	/**
9f95a23c TL	307	* Poll the JSON-RPC client. When any response is available use
	308	* \c spdk_jsonrpc_client_get_response to retrieve it.
	309	*
	310	* This function is not thread safe and should only be called from one thread at
	311	* a time while no other threads are actively \c client object.
11fdf7f2 TL	312	*
11fdf7f2 TL	313	* \param client JSON-RPC client.
9f95a23c TL	314	* \param timeout Time in miliseconds this function will block. -1 block forever, 0 don't block.
	315	*
	316	* \return If no error occurred, this function returns a non-negative number indicating how
	317	* many ready responses can be retrieved. If an error occurred, this function returns one of
	318	* the following negated errno values:
	319	* -ENOTCONN - not connected yet. Try again later.
	320	* -EINVAL - response is detected to be invalid. Client connection should be terminated.
	321	* -ENOSPC - no space to receive another response. User need to retrieve waiting responses.
	322	* -EIO - connection terminated (or other critical error). Client connection should be terminated.
	323	* -ENOMEM - out of memory
	324	*/
	325	int spdk_jsonrpc_client_poll(struct spdk_jsonrpc_client *client, int timeout);
	326
	327	/**
	328	* Return JSON RPC response object representing next available response from client connection.
	329	* Returned pointer must be freed using \c spdk_jsonrpc_client_free_response
11fdf7f2	330	*
9f95a23c TL	331	* This function is not thread safe and should only be called from one thread at
	332	* a time while no other threads are actively \c client object.
	333	*
	334	* \param client
	335	* \return pointer to JSON RPC response object or NULL if no response available.
	336	*/
	337	struct spdk_jsonrpc_client_response *spdk_jsonrpc_client_get_response(struct spdk_jsonrpc_client
	338	*client);
	339
	340	/**
	341	* Free response object obtained from \c spdk_jsonrpc_client_get_response
	342	*
	343	* \param resp pointer to JSON RPC response object. If NULL no operation is performed.
11fdf7f2	344	*/
9f95a23c TL	345	void spdk_jsonrpc_client_free_response(struct spdk_jsonrpc_client_response *resp);
9f95a23c TL	346
11fdf7f2 TL	347
	348	#ifdef __cplusplus
	349	}
	350	#endif
7c673cae FG	351
7c673cae FG	352	#endif