RPC API 说明

本文介绍 PCL CE 启动器 RPC 服务的基本信息、通信格式、请求与响应结构，以及当前对外开放的属性和函数。

PCL CE 内置了一个基于命名管道通信的 RPC 服务。本地第三方进程可以通过该服务与正在运行的启动器交换数据，例如获取启动器版本、读取实时状态、监听日志流，或请求启动器修改部分设置项。

服务信息

启动器运行后，会创建一个命名管道服务端。管道名称格式如下：

PCLCE_RPC@ProcessID

其中，ProcessID 为启动器当前进程的 ID。在 .NET 中，可以通过 System.Diagnostics 命名空间提供的 API 获取进程 ID。

RPC 服务默认开启。若客户端无法连接到管道，可能有以下原因：

• 用户在启动器中启用了“禁用 RPC 服务”设置项；
• 启动器尚未运行；
• 目标进程 ID 不正确；
• 其他进程占用了 RPC 管道；
• 当前进程没有访问该命名管道的权限。

通信格式

请求和响应均使用 UTF-8 编码。

每条消息由两部分组成：

部分	说明
header	必需，位于第一行，用于描述请求或响应的基本信息
content	可选，位于 header 之后，用于传递正文内容

消息正文需要以特殊字符 ESC 结尾。该字符在 ASCII 和 Unicode 中的编码如下：

表示方式	值
八进制	033
十进制	27
十六进制	0x1B
转义写法	\x1B

无论 content 是否为空，请求和响应都必须至少包含两行。也就是说，header 所在行的末尾必须包含换行符。

HEADER
CONTENT\x1B

当 content 为空时，仍然需要保留 header 后的换行符。

HEADER
\x1B

请求格式

请求的 header 格式如下：

TYPE argument

字段	说明
TYPE	请求类型
argument	请求参数

请求类型

类型	说明
GET	获取指定属性的值
SET	修改指定属性的值
REQ	调用指定 RPC 函数

GET

GET 用于读取属性值。

GET version
\x1B

当请求类型为 GET 时，整个 argument 会被视为属性名称。属性名称不区分大小写。

SET

SET 用于修改属性值。

SET SomeProperty
NewValue\x1B

当请求类型为 SET 时，整个 argument 会被视为属性名称。属性名称不区分大小写。

需要写入的新值应放在 content 中。若写入成功，服务端会返回空响应，并通过响应状态表示操作结果。

REQ

REQ 用于调用 RPC 函数。

REQ ping
\x1B

当请求类型为 REQ 时，argument 会按空格分割：

• 第一项为函数名称；
• 剩余部分为函数参数。

函数名称不区分大小写。函数参数区分大小写，但最终行为取决于函数自身的实现。

例如：

REQ SomeFunction arg1 arg2
\x1B

响应格式

响应的 header 格式如下：

STATUS type name

字段	说明
STATUS	响应状态
type	响应内容类型
name	响应内容名称

响应状态

状态	说明
SUCCESS	请求处理成功
FAILURE	请求已被处理，但操作未成功
ERR	请求处理过程中发生错误

响应内容类型

类型	说明
empty	空响应，无正文内容
text	文本内容
json	JSON 内容
base64	Base64 编码内容

当 type 为 empty 时，表示响应没有正文内容。

SUCCESS empty ping
\x1B

当 type 不为 empty 时，响应正文位于 header 后方。

SUCCESS text version
2.11.2-beta.3\x1B

属性权限标记

属性可能带有访问权限标记。权限标记由两个字符组成：

<读取权限><写入权限>

每个字符的含义如下：

字符	含义
r	可直接读取
w	可直接写入
x	操作前需要向用户确认
o	不支持该操作

例如：

标记	说明
ro	可读取，不可写入
ow	不可读取，可写入
rw	可读取，可写入
rx	可读取，写入前需要用户确认
xw	读取前需要用户确认，可写入
xo	读取前需要用户确认，不可写入
ox	不可读取，写入前需要用户确认

对不支持的操作发起请求时，服务端会返回 FAILURE 状态的空响应。

例如：

• 对 ro 或 xo 属性使用 SET；
• 对 ow 或 ox 属性使用 GET。

对需要用户确认的操作发起请求时，启动器会向用户弹窗询问。若用户拒绝，也会返回 FAILURE 状态的空响应。

属性

启动器当前公开以下属性。所有属性值均为文本类型。

属性名	权限	类型	说明	示例
version	ro	text	当前启动器版本	2.11.2-beta.3
branch	ro	text	当前版本分支名	Slow Ring

version

获取当前启动器版本。

请求示例：

GET version
\x1B

响应示例：

SUCCESS text version
2.11.2-beta.3\x1B

branch

获取当前版本分支名。

请求示例：

GET branch
\x1B

响应示例：

SUCCESS text branch
Slow Ring\x1B

函数

RPC 函数的定义格式如下：

函数名 参数 content 返回值类型

函数	参数	content	返回值类型	说明
ping	void	empty	empty	测试 RPC 服务连通性

ping

测试客户端与启动器 RPC 服务之间的连通性。

请求示例：

REQ ping
\x1B

响应示例：

SUCCESS empty ping
\x1B

如果客户端能够收到 SUCCESS 状态的响应，则表示 RPC 服务可正常通信。