基于进程管道通过读写进程标准输入输出实现的 JSON-RPC 客户端。
用法参考『 范例 » 调用其他语言 » Go » RPC 』,或 process.r 扩展库范例。
规则说明:
1、 所有 JSON-RPC 消息必须置于 { } 或 [ ] 内,aardio 输出 JSON 时以换行符结束。
2、
aardio 读取进程输出时获取第一个能成功解析为响应对象的 JSON,
└── 单次调用的响应对象应当是 { } 包含的对象且包含 id 字段。
└── 批量调用的响应对象应当是 [ ] 包含的非空数组且数组元素存在 id 字段。
响应对象 JSON 不要求以换行符结束,忽略进程的其他输出。
客户端总是在发送请求后再读取回复(应答对象的 id 字段必须与请求对象的 id 字段相同)。
关于 JSON-RPC 2.0
创建 JSON-RPC 2.0 客户端,兼容 JSON-RPC 1.0 。
用法请参考『 范例 » 调用其他语言 » Go » RPC 』,
或 process.r 扩展库范例
启动失败返回 null,错误信息。
成功返回 RPC 调用对象
返回对象:processRpcJsonClientObject
启动目标进程,并返回 JSON-RPC 客户端。
目标进程自动绑定作业对象 process.job.limitKill 。
进程管道默认编码设为 UTF-8。
命令行参数可以是一个数组、一个或多个字符串参数,
数组或多个命令行参数调用 process.joinArguments 合并,
不在双引号内、且包含空白或需要转义的参数转义处理后首尾添加双引号
注意:如果参数 @1 为字符串,
每次 RPC 调用时就会自动检测并重启意外退出的 RPC 服务进程。
但每次调用只会尝试重启一次,不会连续重启
创建 JSON-RPC 客户端。
参数 @1 必须指定 process.popen 对象
启动失败返回 null,错误信息。
成功返回 RPC 调用对象
远程对象名或远程方法名字。
远程函数调用成功则第一个返回值为表对象,
└── 该对象的 result 字段为返回值,error 为错误对象,两个字段不会同时存在。
└── error 对象的 message 为错误信息,code 为错误代码,data 为错误附加数据。
└── 如果存在 error 对象,则第 2 个返回值为 error 对象的 JSON 文本格式。
调用失败第一个返回值为 null ,第二个返回值为错误信息
如果调用 rpc.beginTrans 函数开始一个批量调用,
则返回一个可以指定 end 成员函数的对象,服务器应答时自动回调此 end 函数
返回对象:processRpcJsonClientObject
RPC 本地客户端对象
所以本地函数放在这个对象里面
用户不得添加、删除、修改此对象的任何成员
processRpcJsonClientObject.rpc.afterJsonStringify = function(jsonData){
/*可以在这里加密客户端JSON,返回 null 中止本次调用。*/
return jsonData;
}
写入失败时是否自动重启重发。旧模式默认 true;setStrictMode 自动设为 false。
processRpcJsonClientObject.rpc.beforeJsonParse = function(jsonData){
/*可以在这里解密服务端数据,返回 null 中止本次调用。
定义此函数以后,服务端每次输出的 JSON 必须以换行符结束*/
return jsonData;
}
processRpcJsonClientObject.rpc.beforeRequest = function(reqData){
/*此回调事件在发送请求前触发。
reqData.params 是即将发送的参数。*/
return reqData;
}
开始批量调用,注意多数服务器并不支持批量调用。
aardio 实现的 process.rpc.jsonServer 可支持批量调用。
批量调用时单次调用的返回值是一个表
可对返回值指定 end 成员函数,
end 函数会在 commitTrans 提交批量调用成功后被触发
获取或修改编码,此值必须为大写,默认为"UTF-8",
因为 JSON 规定了 Unicode 编码方案,所以不建议也不应该修改这个值
关闭客户端
完成批量调用,注意多数服务器并不支持批量调用。
aardio 实现的 process.rpc.jsonServer 可支持批量调用。
发送 Ctrl+C(SIGINT信号)
信号将传递到与目标进程控制台连接的所有非分离控制台进程
64位目标进程会导致当前控制台暂时关闭
发送 Ctrl+Break(SIGINT信号)
信号将传递到与目标进程控制台连接的所有非分离控制台进程
64位目标进程会导致当前控制台暂时关闭
该函数调用成功有两个返回值:目标进程退出代码,目标进程是否已退出
是否支持 Python 命名参数(kwargs )。
仅适用于 process.python.jsonRpc,仅 varargs 属性为 true 时有效。
调用时命名参数必须写在参数列表最前面,
其后第一个出现的位置参数对应服务端的第一个位置参数
最近请求状态:not_sent / unknown / responded。unknown 时操作可能已发生,禁止盲目重放。
获取最后一次服务器返回的原始数据,
如果控制台已打开或在开发环境中导入 console 库则在控制台输出数据
下载文件时该值为空
严格模式本次错误输出(最多保留末尾 64 KiB)。
严格模式本次未匹配的输出(最多保留末尾 64 KiB)。
发送通知,服务器不返回值,
如果 varargs 属性指定为 true 时将不定个数参数合为数组,
varargs为 false 时直接发送参数
成功返回 true,失败返回 null,错误信息
进程管道对象
目标进程恢复运行
撤消尚未提交的批量调用
启用严格模式:独立递增请求 ID,按 LF 分帧并严格关联完整响应,超时不重发。
仅适用于每个 JSON 响应占一行且以 LF 结束的服务端。
默认关闭自动重启重发;同一客户端不支持并发/重入调用。
等待超时不代表远程操作被取消,应回读真实状态。
目标进程是否仍然运行
目标进程暂停运行
强制关闭进程并释放目标进程对象。
注意如果在构造函数中指定了执行文件路径。
且在目标进程退出后继续调用 RPC 函数。
则会自动重启 RPC 服务进程。
严格模式等待响应的超时毫秒数,默认 30000,必须为正数。
默认值为 true,
值为 true 时将不定个数的参数放入数组发送给服务端
值为 false 时直接将单个参数发送给服务端
JSON-RPC 2.0 一个会制造混乱的地方:
如果params是一个数组,并没有规定是展开为一个参数,还是作为一个数组参数。
目前 aardio 的 RPC 服务端会负责展开数组作为多个参数,
但客户端需要在这里手动设置
值为 JSON-RPC 协议版本:"2.0"
不应该修改这个值
等待目标进程关闭,可选使用一个毫秒值参数设定超时。
超时或失败返回 null,进程退出则返回值1为true,
返回值2为标准输出,返回值3为错误输出,返回值4为退出代码
如被调用进程写满输出缓冲区,而调用进程没有读取,
则被调用进程会一直等待,此函数将无法返回。
改用 readAll 函数读取输入可避免该问题。
等待目标进程关闭,不会阻塞当前线程窗口消息。
可用一个毫秒值参数设定超时。
超时或失败返回 null,进程已退出则返回值1为true,
返回值2为标准输出,返回值3为错误输出,返回值4为退出代码
如果被调用进程写满输出缓冲区,而调用进程没有读取,
则被调用进程会一直等待,此函数将无法返回。
改用 readAll 函数读取输入可避免该问题。
注意如果正在调用异步 logResponse 回显到窗口对象。
则 waitOne 函数仅返回单个值,不读取任何输出
调用远程函数。
如果 varargs 属性指定为 true 时将不定个数参数合为数组,
varargs 为 false 时直接发送参数
远程函数调用成功则第一个返回值为表对象,
└── 该对象的 result 字段为返回值,error 为错误对象,两个字段不会同时存在。
└── error 对象的 message 为错误信息,code 为错误代码,data 为错误附加数据。
└── 如果存在 error 对象,则第 2 个返回值为 error 对象的 JSON 文本格式。
调用失败第一个返回值为 null ,第二个返回值为错误信息
如果调用 rpc.beginTrans 函数开始一个批量调用,
则返回一个可以指定 end 成员函数的对象,服务器应答时自动回调此 end 函数
processRpcJsonClientObject.rpc.onError = function(message){
/*目标进程存在标准库错误输出时触发此函数*/
}