nlib
nn::nlib::msgpack::jsonrpc Namespace Reference

Implements JSON-RPC 2.0. More...

Classes

class  JsonRpcClient
 Class to manage client side JSON-RPC. More...
 
class  JsonRpcRequest
 Class for representing a JSON-RPC request. More...
 
class  JsonRpcRequestReader
 Class that reads the JSON-RPC request. More...
 
class  JsonRpcRequestWriter
 Class to serialize and write the JSON-RPC request to memory. More...
 
class  JsonRpcResponse
 Class for representing the JSON-RPC response. More...
 
class  JsonRpcResponseReader
 Class that reads the JSON-RPC response byte string. More...
 
class  JsonRpcResponseWriter
 Class that writes the JSON-RPC response byte string. More...
 

Typedefs

typedef uint32_t reqid_t
 id type for the JSON-RPC request. More...
 
typedef JsonRpcServerFuncCallError(* JsonRpcServerFunc) (MpObject &param, JsonRpcResponse &response)
 JSON-RPC method handler. More...
 

Enumerations

enum  JsonRpcServerFuncCallError {
  JSONSERVER_OK = 0,
  JSONSERVER_PARSE_ERROR = -32700,
  JSONSERVER_INVALID_REQUEST = -32600,
  JSONSERVER_METHOD_NOT_FOUND = -32601,
  JSONSERVER_INVALID_PARAMS = -32602,
  JSONSERVER_INTERNAL_ERROR = -32603
}
 Return value of the server-side JSON-RPC method handler. More...
 

Functions

errno_t AddJsonRpcServerMethod (const char *method, JsonRpcServerFunc func)
 Sets the JSON-RPC method handler. More...
 
JsonRpcServerFunc GetJsonRpcServerMethod (const char *method)
 Gets the method handler of the JSON-RPC registered by specifying the method name. More...
 
void ClearJsonRpcServerMethodTable ()
 Deletes all registered JSON-RPC method handlers.
 
size_t JsonRpcServerExec (const void *p, size_t n, ReallocOutputStream::UniquePtrType *ptr)
 Creates the JSON-RPC response byte string by processing the JSON-RPC request. More...
 

Detailed Description

Implements JSON-RPC 2.0.

Description
JSON-RPC is stateless and is a lightweight RPC that does not require IDL.
Base transfer protocol is not limited to HTTP, and is defined to be able to use TCP and other protocols.
The client side sends the function call JSON to the server, and the server sends the result JSON to client.
nlib can be implemented on both the client and server sides.
nlib has implemented JSON-RPC 2.0 (JSON-RPC 1.0 is not implemented).
nlib can also use msgpack to communicate instead of JSON.
The user must define the payload, as it is not defined in JSON-RPC or the library.
The jsonrpc sample may be used as reference for this part.
JSON-RPC also contains the following RPC characteristics.
  • Does not require IDL.
  • Can pass function argument types and return values by JSON, and is flexible and active.
  • Can handle batch requests. You can use this function to call multiple requests at the same time.
  • Can run on many protocols, including HTTP and TCP.
  • nlib JSON-RPC may use msgpack instead of JSON for higher efficiency.
Specifically, this option is useful in the following cases.
  • JSON-RPC server communication over a network (which requires implementing security features).
  • Use from locally running processes such as JavaScript. The server side C++ program may directly receive a JSON request created and sent by JavaScript.
  • Definition of services used on other inter-process communication. You can decouple the service provider and service client by making a service accessible by JSON-RPC. The header does not need to be shared.
  • Method to decouple modules. As IDL is not required. The client and server do not need to share any code, including the header, and can be complied separately.
See also
http://www.jsonrpc.org/specification (JSON-RPC)

Typedef Documentation

§ JsonRpcServerFunc

JsonRpcServerFuncCallError(* nn::nlib::msgpack::jsonrpc::JsonRpcServerFunc)(MpObject &param, JsonRpcResponse &response)

JSON-RPC method handler.

Parameters
[in]paramJSON-RPC call function parameter.
[in,out]response
Returns
Indicates an error when the value is anything except 0.
Description
If wanting to return an error that is not defined in JsonRpcServerFuncCallError as a response, call JsonRpcResponse::SetError to set an error, and then return JSONSERVER_OK.

Definition at line 32 of file JsonRpcServerExec.h.

§ reqid_t

id type for the JSON-RPC request.

Description
nlib JSON-RPC can only use positive integers. Generated using JsonRpcClient::GenerateId.
Examples:
msgpack/jsonrpc/jsonrpc.cpp, and msgpack/jsonrpc/server.cpp.

Definition at line 19 of file JsonRpcClient.h.

Enumeration Type Documentation

§ JsonRpcServerFuncCallError

Return value of the server-side JSON-RPC method handler.

Description
An error defined in JSON-RPC 2.0 can be set as a response without setting a response object. This is performed by setting a value other than JSONSERVER_OK.
Enumerator
JSONSERVER_OK 

Returned when the function process is successful.
Set the response and return this value when returning an error unique to the server implementation.

JSONSERVER_PARSE_ERROR 

Sets the JSON-RPC2.0 -32700 error.
Parsing the JSON-RPC request is successful if the JSON-RPC method handler is being called. As a result, users that implement their own JSON-RPC method handler do not use this function.

JSONSERVER_INVALID_REQUEST 

Sets the JSON-RPC2.0 -32600 error.
The JSON-RPC request is already known to be valid if the JSON-RPC method handler is being called. As a result, users that implement their own JSON-RPC method handler do not use this function.

JSONSERVER_METHOD_NOT_FOUND 

Sets the JSON-RPC2.0 -32601 error.
The method is already found if the JSON-RPC method handler is called. As a result, users that implement their own JSON-RPC handler method handler do not use this function.

JSONSERVER_INVALID_PARAMS 

Sets the JSON-RPC2.0 -32602 error.
Returning this value when the JSON-RPC request parameter is not in a format that the handler is designed to process return an error response.

JSONSERVER_INTERNAL_ERROR 

Sets the JSON-RPC2.0 -32603 error.
Returning this value when an error has occurred within the JSON-RPC method handler returns an error response.

Examples:
msgpack/jsonrpc/server.cpp.

Definition at line 23 of file JsonRpcServerExec.h.

Function Documentation

§ AddJsonRpcServerMethod()

nn::nlib::msgpack::jsonrpc::AddJsonRpcServerMethod ( const char *  method,
JsonRpcServerFunc  func 
)

Sets the JSON-RPC method handler.

Parameters
[in]methodMethod name.
[in]funcJSON-RPC method handler.
Return values
0Success.
EINVALmethod or func is NULL.
ENOMEMmemory allocation failed.
Examples:
msgpack/jsonrpc/server.cpp.

§ GetJsonRpcServerMethod()

nn::nlib::msgpack::jsonrpc::GetJsonRpcServerMethod ( const char *  method)

Gets the method handler of the JSON-RPC registered by specifying the method name.

Parameters
[in]methodMethod name.
Returns
JSON-RPC method handler.

§ JsonRpcServerExec()

nn::nlib::msgpack::jsonrpc::JsonRpcServerExec ( const void *  p,
size_t  n,
ReallocOutputStream::UniquePtrType ptr 
)

Creates the JSON-RPC response byte string by processing the JSON-RPC request.

Parameters
[in]pPointer to the JSON-RPC request byte string.
[in]nSize of the JSON-RPC request byte string.
[out]ptrPointer to the JSON-RPC response byte string.
Returns
Size of the JSON-RPC response byte string.
Description
This process is executed in a single thread. Secure the server availability by running this function in worker threads as needed.
Returns a JSON response to JSON-RPC requests, and a msgpack response to msgpack requests.
The user must actually send the byte string to the client.
Examples:
msgpack/jsonrpc/server.cpp.