YStudio Y++

MQTT类

Y++ / YStudio 开发文档 · 一点滴

类对象支持库。路径：支持库 → 扩展类库 → MQTT类。

类型名必须写完整「MQTT类」。声明时自动创建。

本类是自研的 MQTT 3.1.1 客户端，也可以在同一进程里当 Broker。传输用 mqtt://（TCP）和 mqtts://（TLS）。QoS 支持 0、1 和 2。大于 2 会失败，原因在 取错误()。

开通后才能在 IDE 里编译使用本类。编进用户程序之后，运行时不再向授权服务器验票。

硬约束

  1. 类型名必须写「MQTT类」。
  2. 先注册事件，再 连接 或 启动。
  3. 回调里的文本只在函数返回前有效，不要在回调里长时间阻塞。

快速开始

MQTT类 服务
服务.启动(1883, "127.0.0.1")

MQTT类 客户
如果 (客户.连接_同步("mqtt://127.0.0.1:1883")) {
    客户.订阅("demo/#", 0)
    客户.发布("demo/hi", "hello", 0, 0)
}

事件

回调形参固定如下。传 0 表示取消注册。

方法 形参
客户进入 / 连接成功 (整数 连接ID, 文本 IP, 整数 端口, 文本 IP端口)
连接失败 (文本 原因)
数据到达 (整数 连接ID, 文本 主题, 文本 载荷, 整数 QoS, 整数 保留)
数据到达字节集 (整数 连接ID, 文本 主题, 字节集 载荷, 整数 QoS, 整数 保留)
客户离开 / 连接关闭 (整数 连接ID, 文本 IP, 整数 端口, 文本 IP端口, 整数 原因码, 文本 原因)
心跳超时 (整数 连接ID, 文本 IP, 整数 端口, 文本 IP端口)

客户端连接成功时，连接 ID 为 1。Broker 上每个接入连接有自己的 ID。

合法 UTF-8 载荷会触发 数据到达。数据到达字节集 每次都有。

客户端

  • 连接 / 连接_同步：mqtt://主机:端口 或 mqtts://主机:端口
  • 连接主机 / 连接主机_同步：主机、端口、是否 TLS
  • 置客户端ID、置用户名、置密码、置清理会话、置遗嘱、置心跳（秒）
  • 订阅、取消订阅、发布、发布字节集
  • 断开、重置、是否已连接、取错误

置心跳 的单位是秒。0 表示不按 Keep Alive 发 PING。

Broker

  • 启动 或 监听：端口和绑定地址
  • 停止、断开连接(连接ID)、是否监听
  • 置最大客户数：0 为不限制
  • 置允许用户：加入用户名和密码。用户名为空则取消校验
  • 在 Broker 会话上调用 发布，会转给匹配的订阅者，并写入保留消息

主题过滤支持 +（一层）和 #（剩余层）。同一连接上再次 订阅 同一过滤时会更新 QoS，不会叠两条。重叠过滤按其中较高的 QoS 投递一次。

TLS

与 WebSocket 的证书参数同类：置TLS、置TLS验证、置TLS主机名、置TLS证书（PFX）、置TLS根证书。

Broker 要开 mqtts 时，先 置TLS(1) 并 置TLS证书，再 启动。

引擎

置引擎("native") 使用自研实现，这是默认值。置引擎("paho") 留给以后编入第三方库；当前未编入时返回假，取错误() 为「未编译该 MQTT 引擎」。用户程序接口不变。