ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

include/json_rpc.h: add comments for public APIs

Browse Source 
Change-Id: I64ea74b532a1d1544f294f737eba68b5798e0918
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/403459
Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Changpeng Liu <changpeng.liu@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>
This commit is contained in:
Yanbo Zhou 2018-03-12 15:33:10 +08:00 committed by Jim Harris
parent 6450f07e4d
commit 43ae70924c
1 changed files with 47 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
include/spdk/jsonrpc.h
View File

@ -61,27 +61,58 @@ struct spdk_jsonrpc_request;
* *
* The user should respond by calling one of spdk_jsonrpc_begin_result() or * The user should respond by calling one of spdk_jsonrpc_begin_result() or
* spdk_jsonrpc_send_error_response(). * 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)( typedef void (*spdk_jsonrpc_handle_request_fn)(
struct spdk_jsonrpc_request *request, struct spdk_jsonrpc_request *request,
const struct spdk_json_val *method, const struct spdk_json_val *method,
const struct spdk_json_val *params); const struct spdk_json_val *params);
/**
* 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 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); 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); 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); void spdk_jsonrpc_server_shutdown(struct spdk_jsonrpc_server *server);
/** /**
* Begin building a response to a JSON-RPC request. * Begin building a response to a JSON-RPC request.
* *
* \param request JSON-RPC request to respond to. * If this function returns non-NULL, the user must call spdk_jsonrpc_end_result()
* \return JSON write context to write the response object to, or NULL if no response is necessary. * on the request after writing the desired response object to the spdk_json_write_ctx.
* *
* If this function returns non-NULL, the user must call spdk_jsonrpc_end_result() on the request * \param request JSON-RPC request to respond to.
* after writing the desired response object to the spdk_json_write_ctx.
* \return JSON write context to write the response object to, or NULL if no
* response is necessary.
*/ */
struct spdk_json_write_ctx *spdk_jsonrpc_begin_result(struct spdk_jsonrpc_request *request); struct spdk_json_write_ctx *spdk_jsonrpc_begin_result(struct spdk_jsonrpc_request *request);
@ -96,13 +127,13 @@ void spdk_jsonrpc_end_result(struct spdk_jsonrpc_request *request, struct spdk_j
/** /**
* Send an error response to a JSON-RPC request. * Send an error response to a JSON-RPC request.
* *
* \param request JSON-RPC request to respond to. * This is shorthand for spdk_jsonrpc_begin_result() + spdk_jsonrpc_end_result()
* \param error_code Integer error code to return (may be one of the SPDK_JSONRPC_ERROR_ errors, * with an error object.
* or a custom error code).
* \param msg String error message to return.
* *
* This is shorthand for spdk_jsonrpc_begin_result() + spdk_jsonrpc_end_result() with an error * \param request JSON-RPC request to respond to.
* object. * \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, void spdk_jsonrpc_send_error_response(struct spdk_jsonrpc_request *request,
int error_code, const char *msg); int error_code, const char *msg);
@ -110,12 +141,12 @@ void spdk_jsonrpc_send_error_response(struct spdk_jsonrpc_request *request,
/** /**
* Send an error response to a JSON-RPC request. * Send an error response to a JSON-RPC request.
* *
* \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.
*
* This is shorthand for printf() + spdk_jsonrpc_send_error_response(). * 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, void spdk_jsonrpc_send_error_response_fmt(struct spdk_jsonrpc_request *request,
int error_code, const char *fmt, ...) __attribute__((format(printf, 3, 4))); int error_code, const char *fmt, ...) __attribute__((format(printf, 3, 4)));