
---@alias mqtt_read_func fun(size:integer):string|false, string?

---@class mqtt_packet*
---@field type integer MQTT 包类型。
---@field packet_id? integer Packet Identifier。
---@field properties? table MQTT v5 属性。
---@field user_properties? table MQTT v5 用户属性。

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

--- 返回组合包长度。
---@return integer length
function mqtt_combined_packet:len() end

--- 追加包片段。
---@param part string|mqtt_combined_packet*
function mqtt_combined_packet:append(part) end

---@class mqtt_protocol*
---@field max_variable_length integer 可变长度字段最大值。
---@field packet_type table<string|integer, integer|string> MQTT 控制包类型映射。
---@field connack_rc table<integer, string> CONNACK 原因码说明。
---@field packet_mt table 通用包 metatable。
---@field connack_packet_mt table CONNACK 包 metatable。
---@type mqtt_protocol*
local M = {}

M.max_variable_length = 268435455
M.packet_type = nil
M.connack_rc = nil
M.packet_mt = nil
M.connack_packet_mt = nil

--- 编码 uint8。
---@param value integer
---@return string bytes
function M.make_uint8(value) end

--- 编码 uint16。
---@param value integer
---@return string bytes
function M.make_uint16(value) end

--- 编码 uint32。
---@param value integer
---@return string bytes
function M.make_uint32(value) end

--- 编码 MQTT UTF-8 字符串。
---@param value string
---@return string bytes
function M.make_string(value) end

--- 编码 MQTT 可变长度整数。
---@param value integer
---@return integer ... bytes
function M.make_var_length(value) end

--- 编码仅允许 0 或 1 的 uint8。
---@param value integer
---@return string bytes
function M.make_uint8_0_or_1(value) end

--- 编码非零 uint16。
---@param value integer
---@return string bytes
function M.make_uint16_nonzero(value) end

--- 编码非零可变长度整数。
---@param value integer
---@return integer ... bytes
function M.make_var_length_nonzero(value) end

--- 解析 MQTT UTF-8 字符串。
---@param read_func mqtt_read_func
---@return string|false value
---@return string? errMsg
function M.parse_string(read_func) end

--- 解析 uint8。
---@param read_func mqtt_read_func
---@return integer|false value
---@return string? errMsg
function M.parse_uint8(read_func) end

--- 解析仅允许 0 或 1 的 uint8。
---@param read_func mqtt_read_func
---@return integer|false value
---@return string? errMsg
function M.parse_uint8_0_or_1(read_func) end

--- 解析 uint16。
---@param read_func mqtt_read_func
---@return integer|false value
---@return string? errMsg
function M.parse_uint16(read_func) end

--- 解析非零 uint16。
---@param read_func mqtt_read_func
---@return integer|false value
---@return string? errMsg
function M.parse_uint16_nonzero(read_func) end

--- 解析 uint32。
---@param read_func mqtt_read_func
---@return integer|false value
---@return string? errMsg
function M.parse_uint32(read_func) end

--- 解析 MQTT 可变长度整数。
---@param read_func mqtt_read_func
---@return integer|false value
---@return string? errMsg
function M.parse_var_length(read_func) end

--- 解析非零可变长度整数。
---@param read_func mqtt_read_func
---@return integer|false value
---@return string? errMsg
function M.parse_var_length_nonzero(read_func) end

--- 编码 MQTT 固定头。
---@param packetType integer MQTT 包类型。
---@param flags integer 固定头 flags。
---@param length integer 剩余长度。
---@return string bytes
function M.make_header(packetType, flags, length) end

--- 检查 QoS 是否有效。
---@param value integer
---@return boolean valid
function M.check_qos(value) end

--- 检查 Packet Identifier 是否有效。
---@param value integer
---@return boolean valid
function M.check_packet_id(value) end

--- 取得下一个 Packet Identifier。
---@param current? integer 当前 packet id。
---@return integer nextId 下一个 packet id。
function M.next_packet_id(current) end

--- 判断指定包是否需要 Packet Identifier。
---@param args mqtt_packet* 包参数。
---@return boolean required 是否需要。
function M.packet_id_required(args) end

--- 合并多个包片段。
---@param ... string|mqtt_combined_packet*
---@return mqtt_combined_packet* packet 组合包。
function M.combine(...) end

--- 将包渲染为可读字符串。
---@param packet mqtt_packet*
---@return string text 可读文本。
function M.packet_tostring(packet) end

--- 开始解析 MQTT 包。
---@param read_func mqtt_read_func
---@return integer|false packetType
---@return integer|string flagsOrErr
---@return table? input 包输入对象。
function M.start_parse_packet(read_func) end

--- 解析 CONNECT 包。
---@param read_func mqtt_read_func
---@param version? integer 期望协议版本。
---@return mqtt_packet*|false packet
---@return string? errMsg
function M.parse_packet_connect(read_func, version) end

--- 从已读入的输入对象继续解析 CONNECT 包。
---@param input table 包输入对象。
---@param version? integer 期望协议版本。
---@return mqtt_packet*|false packet
---@return string? errMsg
function M.parse_packet_connect_input(input, version) end

return M
