
---@class mqtt_client_module*
---@type mqtt_client_module*
local M = {}

---@class mqtt_client_object*
local mqtt_client_object = {}

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

--- 注册事件回调。可传入 `(event, callback)` 或 `{ event = callback }`。
---@param event mqtt_event|table 事件名或事件表。
---@param callback? function 回调。
function mqtt_client_object:on(event, callback) end

--- 移除事件回调。
---@param event mqtt_event 事件名。
---@param callback function 回调。
---@return boolean ok 是否成功。
function mqtt_client_object:off(event, callback) end

--- 订阅主题。
---@param args mqtt_subscribe_options* 订阅参数。
---@return integer|false packetId 成功时返回 packet id。
---@return string? errMsg 错误信息。
function mqtt_client_object:subscribe(args) end

--- 取消订阅主题。
---@param args mqtt_unsubscribe_options* 取消订阅参数。
---@return integer|false packetId 成功时返回 packet id。
---@return string? errMsg 错误信息。
function mqtt_client_object:unsubscribe(args) end

--- 发布消息。
---@param args mqtt_publish_options* 发布参数。
---@return true|integer|false result QoS 0 成功返回 true，其他 QoS 成功返回 packet id。
---@return string? errMsg 错误信息。
function mqtt_client_object:publish(args) end

--- 确认收到的 PUBLISH 消息。
---@param msg table PUBLISH 包。
---@param rc? integer MQTT v5 原因码。
---@param properties? table MQTT v5 属性。
---@param user_properties? table MQTT v5 用户属性。
---@return boolean ok 是否成功。
---@return string? errMsg 错误信息。
function mqtt_client_object:acknowledge(msg, rc, properties, user_properties) end

--- 发送 DISCONNECT 并关闭连接。
---@param rc? integer MQTT v5 原因码。
---@param properties? table MQTT v5 属性。
---@param user_properties? table MQTT v5 用户属性。
---@return boolean ok 是否成功。
---@return string? errMsg 错误信息。
function mqtt_client_object:disconnect(rc, properties, user_properties) end

--- 发送 MQTT v5 AUTH 包。
---@param rc? integer 原因码。
---@param properties? table MQTT v5 属性。
---@param user_properties? table MQTT v5 用户属性。
---@return boolean ok 是否成功。
---@return string? errMsg 错误信息。
function mqtt_client_object:auth(rc, properties, user_properties) end

--- 立即关闭网络连接。
---@param reason? string 关闭原因。
---@return boolean ok 是否成功。
function mqtt_client_object:close_connection(reason) end

--- 打开网络连接并发送 CONNECT 包。
---@return boolean ok 是否成功。
---@return string? errMsg 错误信息。
function mqtt_client_object:start_connecting() end

--- 打开到底层 broker 的网络连接。
---@return boolean ok 是否成功。
---@return string? errMsg 错误信息。
function mqtt_client_object:open_connection() end

--- 发送 CONNECT 包。
---@return boolean ok 是否成功。
---@return string? errMsg 错误信息。
function mqtt_client_object:send_connect() end

--- 发送 PINGREQ 包。
---@return boolean ok 是否成功。
---@return string? errMsg 错误信息。
function mqtt_client_object:send_pingreq() end

--- 绑定或解绑 IO loop。
---@param loop? mqtt_ioloop_object* IO loop。
function mqtt_client_object:set_ioloop(loop) end

return M
