nlib
nn::nlib::msgpack::jsonrpc 名前空間

JSON-RPC 2.0 を実装しています。 [詳解]

クラス

class  JsonRpcClient
 JSON-RPCのクライアント側の管理を行うクラスです。 [詳解]
 
class  JsonRpcRequest
 JSON-RPCのリクエストを表すクラスです。 [詳解]
 
class  JsonRpcRequestReader
 JSON-RPCリクエストを読み込むためのクラスです。 [詳解]
 
class  JsonRpcRequestWriter
 JSON-RPCのリクエストをシリアライズしてメモリに書きこむためのクラスです。 [詳解]
 
class  JsonRpcResponse
 JSON-RPCのレスポンスを表すクラスです。 [詳解]
 
class  JsonRpcResponseReader
 JSON-RPCのレスポンスのバイト列を読み込むためのクラスです。 [詳解]
 
class  JsonRpcResponseWriter
 JSON-RPCのレスポンスのバイト列を書きこむためのクラスです。 [詳解]
 

型定義

typedef uint32_t reqid_t
 JSON-RPCのリクエストに付与されるidの型です。 [詳解]
 
typedef JsonRpcServerFuncCallError(* JsonRpcServerFunc) (MpObject &param, JsonRpcResponse &response)
 JSON-RPCのメソッドハンドラです。 [詳解]
 

列挙型

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
}
 サーバー側のJSON-RPCメソッドハンドラの戻り値です。 [詳解]
 

関数

errno_t AddJsonRpcServerMethod (const char *method, JsonRpcServerFunc func)
 JSON-RPCのメソッドハンドラを登録します。 [詳解]
 
JsonRpcServerFunc GetJsonRpcServerMethod (const char *method)
 メソッド名を指定して登録されているJSON-RPCのメソッドハンドラを取得します。 [詳解]
 
void ClearJsonRpcServerMethodTable ()
 登録されているJSON-RPCのメソッドハンドラを全て削除します。
 
size_t JsonRpcServerExec (const void *p, size_t n, ReallocOutputStream::UniquePtrType *ptr)
 JSON-RPCリクエストを処理してJSON-RPCレスポンスのバイト列を作成します。 [詳解]
 

詳解

JSON-RPC 2.0 を実装しています。

説明
JSON-RPC(http://www.jsonrpc.org/specification)は、ステートレスで軽いRPCでIDLを必要としません。
ベースの伝送プロトコルは、HTTPに限らす、TCP他のプロトコルでも利用できるように定義されています。
クライアント側は、関数呼び出しに相当するJSONをサーバーに送信し、サーバー側は実行結果をJSONでクライアントに返信します。
nlibではクライアント側もサーバー側も実装することができます。
nlibはJSON-RPC 2.0を実装しています(JSON-RPC 1.0については実装されていません)。
また、nlibではJSONの代わりにmsgpackを利用して通信することも可能です。
実際のデータの通信部分はJSON-RPCやライブラリには定義されていないので、ユーザーが定義する必要があります。
この部分についてはjsonrpcサンプルを参考にすることができます。
JSON-RPCは、RPCとしては以下の様な特色を持ちます。
  • IDLを必要としません。
  • 関数の引数型や戻り値をJSONで渡すことができ、動的で柔軟です。
  • バッチリクエストが可能です。これは複数のリクエストを1つにまとめて呼び出す機能です。
  • HTTPやTCP他、様々なプロトコルの上に載せることができます。
  • nlibのJSON-RPCはJSONの代わりにより効率のよいmsgpackを利用して通信することが可能です。
具体的には以下の様な用途に利用可能だと思われます。
  • ネットワークを介したJSON-RPCサーバーとの通信(セキュリティの確保が必要です)
  • ローカルで走るjavascript等からの利用。javascriptがJSONのリクエストを作成し送信することで、サーバー側のC++プログラムが直接受けることができます。
  • その他プロセス間通信で利用されるサービスの定義。サービスをJSON-RPCで利用可能にしておけば、サービスを行う側とサービスを受ける側を疎結合にすることが可能です。ヘッダの共有も必要ありません。
  • モジュール間を疎結合にするための手段として。IDLを必要としないので、クライアント側とサーバー側はヘッダを含むコードを一切共有する必要がなく、別々にコンパイル可能です。

型定義詳解

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

JSON-RPCのメソッドハンドラです。

引数
[in]paramJSON-RPC呼び出し関数のパラメータ
[in,out]response
戻り値
0以外の場合はエラー
説明
JsonRpcServerFuncCallErrorに定義されたエラー以外のエラーをレスポンスとして返したい場合は、 JsonRpcResponse::SetError() を呼び出しエラーを設定して JSONSERVER_OK を返します。

JsonRpcServerExec.h32 行目に定義があります。

JSON-RPCのリクエストに付与されるidの型です。

説明
nlibのJSON-RPCでは正の整数のみが可能です。 JsonRpcClient::GenerateId()を用いて生成します。
各種例:
msgpack/jsonrpc/jsonrpc.cpp, msgpack/jsonrpc/server.cpp.

JsonRpcClient.h19 行目に定義があります。

列挙型詳解

サーバー側のJSON-RPCメソッドハンドラの戻り値です。

説明
JSONSERVER_OK以外を設定した場合、JSON-RPC 2.0で定義されているエラーをレスポンスオブジェクトを設定することなくレスポンスに設定することができます。
列挙値
JSONSERVER_OK 

関数の処理が成功した場合に返します。
また、サーバー実装独自のエラーを返す場合も、レスポンスを設定してこの値を返します。

JSONSERVER_PARSE_ERROR 

JSON-RPC2.0の-32700エラーを設定します。
JSON-RPCのメソッドハンドラが呼ばれている場合は、既にJSON-RPCリクエストのパースは成功しているので、JSON-RPCメソッドハンドラを実装するユーザーが使用することはありません。

JSONSERVER_INVALID_REQUEST 

JSON-RPC2.0の-32600エラーを設定します。
JSON-RPCのメソッドハンドラが呼ばれている場合は、既に有効なJSON-RPCリクエストであることが確認されているので、JSON-RPCメソッドハンドラを実装するユーザーが使用することはありません。

JSONSERVER_METHOD_NOT_FOUND 

JSON-RPC2.0の-32601エラーを設定します。
JSON-RPCのメソッドハンドラが呼ばれている場合は、既にメソッドは見つかっているので、JSON-RPCメソッドハンドラを実装するユーザーが使用することはありません。

JSONSERVER_INVALID_PARAMS 

JSON-RPC2.0の-32602エラーを設定します。
JSON-RPCリクエストのパラメータがハンドラの処理すべき形式でない場合に、この値を返すことで、エラーレスポンスを返すことができます。

JSONSERVER_INTERNAL_ERROR 

JSON-RPC2.0の-32603エラーを設定します。
JSON-RPCメソッドハンドラ内部でのエラーが発生した場合に、この値を返すことで、エラーレスポンスを返すことができます。

各種例:
msgpack/jsonrpc/server.cpp.

JsonRpcServerExec.h23 行目に定義があります。

関数詳解

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

JSON-RPCのメソッドハンドラを登録します。

引数
[in]methodメソッド名
[in]funcJSON-RPCのメソッドハンドラ
戻り値
0成功しました。
EINVALmethod 又はfuncNULLの場合
ENOMEMメモリの確保に失敗した場合
各種例:
msgpack/jsonrpc/server.cpp.
nn::nlib::msgpack::jsonrpc::GetJsonRpcServerMethod ( const char *  method)

メソッド名を指定して登録されているJSON-RPCのメソッドハンドラを取得します。

引数
[in]methodメソッド名
戻り値
JSON-RPCのメソッドハンドラ
nn::nlib::msgpack::jsonrpc::JsonRpcServerExec ( const void *  p,
size_t  n,
ReallocOutputStream::UniquePtrType ptr 
)

JSON-RPCリクエストを処理してJSON-RPCレスポンスのバイト列を作成します。

引数
[in]pJSON-RPCリクエストのバイト列へのポインタ
[in]nJSON-RPCリクエストのバイト列のサイズ
[out]ptrJSON-RPCレスポンスのバイト列が格納されるポインタ
戻り値
JSON-RPCレスポンスのバイト列のサイズ
説明
処理はシングルスレッドで行われます。 必要ならばこの関数をワーカースレッドで実行する等して、サーバーの応答性能を確保してください。
JSON-RPCリクエストがJSONだった場合はJSONで、msgpackだった場合はmsgpackでレスポンスを返します。
ユーザーはバイト列をクライアントに実際に送信する必要があります。
各種例:
msgpack/jsonrpc/server.cpp.