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

63
include/spdk/jsonrpc.h
View File

@ -60,28 +60,59 @@ struct spdk_jsonrpc_request;
* 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().
* 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);
/**
* 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);
/**
* Begin building a response to a JSON-RPC request.
*
* \param request JSON-RPC request to respond to.
* \return JSON write context to write the response object to, or NULL if no response is necessary.
* 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.
*
* 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 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);
@ -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.
*
* \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.
* This is shorthand for spdk_jsonrpc_begin_result() + spdk_jsonrpc_end_result()
* with an error object.
*
* 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);
@ -110,12 +141,12 @@ void spdk_jsonrpc_send_error_response(struct spdk_jsonrpc_request *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().
*
* \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)));