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

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

--- Create an MQTT client instance.
---@param opts mqtt_client_options* Create parameters.
---@return mqtt_client_object* client Client instance.
function M.create(opts) end

--- Register event callback. You can pass in `(event, callback)` or `{ event = callback }`.
---@param event mqtt_event|table Event name or event table.
---@param callback? function callback.
function mqtt_client_object:on(event, callback) end

--- Remove event callback.
---@param event mqtt_event Event name.
---@param callback function callback.
---@return boolean ok Whether it is successful or not.
function mqtt_client_object:off(event, callback) end

--- Subscribe to topics.
---@param args mqtt_subscribe_options* Subscription parameters.
---@return integer|false packetId Returns packet id on success.
---@return string? errMsg error message.
function mqtt_client_object:subscribe(args) end

--- Unsubscribe from the topic.
---@param args mqtt_unsubscribe_options* Unsubscribe parameters.
---@return integer|false packetId Returns packet id on success.
---@return string? errMsg error message.
function mqtt_client_object:unsubscribe(args) end

--- Post a message.
---@param args mqtt_publish_options* Release parameters.
---@return true|integer|false result QoS 0 Returns true if successful, and returns packet id if other QoS are successful.
---@return string? errMsg error message.
function mqtt_client_object:publish(args) end

--- Acknowledge the receipt of the PUBLISH message.
---@param msg table PUBLISH Bag.
---@param rc? integer MQTT v5 Reason code.
---@param properties? table MQTT v5 property.
---@param user_properties? table MQTT v5 User attributes.
---@return boolean ok Whether it is successful or not.
---@return string? errMsg error message.
function mqtt_client_object:acknowledge(msg, rc, properties, user_properties) end

--- Send DISCONNECT and close the connection.
---@param rc? integer MQTT v5 Reason code.
---@param properties? table MQTT v5 property.
---@param user_properties? table MQTT v5 User attributes.
---@return boolean ok Whether it is successful or not.
---@return string? errMsg error message.
function mqtt_client_object:disconnect(rc, properties, user_properties) end

--- Send MQTT v5 AUTH packet.
---@param rc? integer Reason code.
---@param properties? table MQTT v5 property.
---@param user_properties? table MQTT v5 User attributes.
---@return boolean ok Whether it is successful or not.
---@return string? errMsg error message.
function mqtt_client_object:auth(rc, properties, user_properties) end

--- Close the network connection immediately.
---@param reason? string Reason for closure.
---@return boolean ok Whether it is successful or not.
function mqtt_client_object:close_connection(reason) end

--- Open a network connection and send a CONNECT packet.
---@return boolean ok Whether it is successful or not.
---@return string? errMsg error message.
function mqtt_client_object:start_connecting() end

--- Open a network connection to the underlying broker.
---@return boolean ok Whether it is successful or not.
---@return string? errMsg error message.
function mqtt_client_object:open_connection() end

--- Send CONNECT packet.
---@return boolean ok Whether it is successful or not.
---@return string? errMsg error message.
function mqtt_client_object:send_connect() end

--- Send PINGREQ packet.
---@return boolean ok Whether it is successful or not.
---@return string? errMsg error message.
function mqtt_client_object:send_pingreq() end

--- Bind or unbind the IO loop.
---@param loop? mqtt_ioloop_object* IO loop。
function mqtt_client_object:set_ioloop(loop) end

return M
