
--------------------------------------------------------------------------------
-- MQTT module
--------------------------------------------------------------------------------

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

---@class mqtt_will_options*
---@field topic string Wills Topics.
---@field payload string Will payload.
---@field qos? integer QoS，0、1 or 2.
---@field retain? boolean Whether to retain.
---@field properties? table MQTT v5 property.
---@field user_properties? table MQTT v5 User attributes.

---@class mqtt_client_options*
---@field uri string MQTT broker URI， Typically host:port or host.
---@field clean boolean Whether to use clean session/start.
---@field version? integer MQTT Protocol version, use `mqtt.v311` or `mqtt.v50`.
---@field id? string Client ID.
---@field username? string username.
---@field password? string password.
---@field secure? boolean|table Whether to use TLS, or pass in LuaSec parameters.
---@field will? mqtt_will_options* Will message.
---@field keep_alive? integer keep alive Number of seconds.
---@field properties? table MQTT v5 property.
---@field user_properties? table MQTT v5 User attributes.
---@field reconnect? boolean|number Whether to reconnect, or the number of seconds between reconnections.
---@field connector? mqtt_connector* Custom network connector.
---@field ssl_module? string LuaSec Compatible module name.

---@class mqtt_publish_options*
---@field topic string theme.
---@field payload? string load.
---@field qos? integer QoS，0、1 or 2.
---@field retain? boolean Whether to retain.
---@field dup? boolean Whether it is a duplicate release.
---@field properties? table MQTT v5 property.
---@field user_properties? table MQTT v5 User attributes.
---@field callback? fun(packet:table, client:mqtt_client_object*) Confirm callback.

---@class mqtt_subscribe_options*
---@field topic string theme.
---@field qos? integer QoS，0、1 or 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 property.
---@field user_properties? table MQTT v5 User attributes.
---@field callback? fun(packet:table, client:mqtt_client_object*) Subscription confirmation callback.

---@class mqtt_unsubscribe_options*
---@field topic string theme.
---@field properties? table MQTT v5 property.
---@field user_properties? table MQTT v5 User attributes.
---@field callback? fun(packet:table, client:mqtt_client_object*) Unsubscribe confirmation callback.

---@class mqtt_client_object*
---@field args mqtt_client_options* Create a copy of the parameters.
---@field connection table? Current network connection.

---@class mqtt*
---@field v311 integer MQTT v3.1.1 Protocol version constant.
---@field v50 integer MQTT v5.0 Protocol version constant.
---@field _VERSION string luamqtt Version.
---@type mqtt*
local M = {}

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

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

--- Get the default IO loop.
---@param autocreate? boolean Whether to create automatically.
---@param args? mqtt_ioloop_options* Create parameters.
---@return mqtt_ioloop_object*? loop Default IO loop.
function M.get_ioloop(autocreate, args) end

--- Add the client or loop function to the default IO loop and run it.
---@param ... mqtt_client_object*|function Client or loop function.
---@return any result Running results.
function M.run_ioloop(...) end

--- Runs a synchronous input and output loop against a single client.
---@param client mqtt_client_object* client.
---@return false? ok false on failure.
---@return string? errMsg error message.
function M.run_sync(client) end

return M
