
--------------------------------------------------------------------------------
-- MQTT 模块
--------------------------------------------------------------------------------

---@alias mqtt_event
---| '"connect"'
---| '"subscribe"'
---| '"unsubscribe"'
---| '"message"'
---| '"acknowledge"'
---| '"error"'
---| '"close"'
---| '"auth"'

---@class mqtt_will_options*
---@field topic string 遗嘱主题。
---@field payload string 遗嘱载荷。
---@field qos? integer QoS，0、1 或 2。
---@field retain? boolean 是否保留。
---@field properties? table MQTT v5 属性。
---@field user_properties? table MQTT v5 用户属性。

---@class mqtt_client_options*
---@field uri string MQTT broker URI，通常为 host:port 或 host。
---@field clean boolean 是否使用 clean session/start。
---@field version? integer MQTT 协议版本，使用 `mqtt.v311` 或 `mqtt.v50`。
---@field id? string 客户端 ID。
---@field username? string 用户名。
---@field password? string 密码。
---@field secure? boolean|table 是否使用 TLS，或传入 LuaSec 参数。
---@field will? mqtt_will_options* 遗嘱消息。
---@field keep_alive? integer keep alive 秒数。
---@field properties? table MQTT v5 属性。
---@field user_properties? table MQTT v5 用户属性。
---@field reconnect? boolean|number 是否重连，或重连间隔秒数。
---@field connector? mqtt_connector* 自定义网络连接器。
---@field ssl_module? string LuaSec 兼容模块名。

---@class mqtt_publish_options*
---@field topic string 主题。
---@field payload? string 载荷。
---@field qos? integer QoS，0、1 或 2。
---@field retain? boolean 是否保留。
---@field dup? boolean 是否为重复发布。
---@field properties? table MQTT v5 属性。
---@field user_properties? table MQTT v5 用户属性。
---@field callback? fun(packet:table, client:mqtt_client_object*) 确认回调。

---@class mqtt_subscribe_options*
---@field topic string 主题。
---@field qos? integer QoS，0、1 或 2。
---@field no_local? boolean MQTT v5 no local。
---@field retain_as_published? boolean MQTT v5 retain as published。
---@field retain_handling? integer MQTT v5 retain handling。
---@field properties? table MQTT v5 属性。
---@field user_properties? table MQTT v5 用户属性。
---@field callback? fun(packet:table, client:mqtt_client_object*) 订阅确认回调。

---@class mqtt_unsubscribe_options*
---@field topic string 主题。
---@field properties? table MQTT v5 属性。
---@field user_properties? table MQTT v5 用户属性。
---@field callback? fun(packet:table, client:mqtt_client_object*) 取消订阅确认回调。

---@class mqtt_client_object*
---@field args mqtt_client_options* 创建参数副本。
---@field connection table? 当前网络连接。

---@class mqtt*
---@field v311 integer MQTT v3.1.1 协议版本常量。
---@field v50 integer MQTT v5.0 协议版本常量。
---@field _VERSION string luamqtt 版本。
---@type mqtt*
local M = {}

M.v311 = 4
M.v50 = 5
M._VERSION = nil

--- 创建 MQTT 客户端。
---@param opts mqtt_client_options* 创建参数。
---@return mqtt_client_object* client 客户端实例。
function M.client(opts) end

--- 获取默认 IO loop。
---@param autocreate? boolean 是否自动创建。
---@param args? mqtt_ioloop_options* 创建参数。
---@return mqtt_ioloop_object*? loop 默认 IO loop。
function M.get_ioloop(autocreate, args) end

--- 将客户端或循环函数加入默认 IO loop 并运行。
---@param ... mqtt_client_object*|function 客户端或循环函数。
---@return any result 运行结果。
function M.run_ioloop(...) end

--- 对单个客户端运行同步输入输出循环。
---@param client mqtt_client_object* 客户端。
---@return false? ok 失败时为 false。
---@return string? errMsg 错误信息。
function M.run_sync(client) end

return M
