---@meta socket.core

--------------------------------------------------------------------------------
-- LuaSocket C core 模块
--------------------------------------------------------------------------------

---@alias socket_core_timeout number|nil
---@alias socket_shutdown_mode 'receive'|'send'|'both'

---@class socket_core_tcp*: socket_tcp_client*
local socket_core_tcp = {}

---@class socket_core_udp*: socket_udp_client*
local socket_core_udp = {}

---@class socket_core_dns*: socket_dns*
local socket_core_dns = {}

---@class socket_core*
---@field _VERSION string 版本
---@field _DEBUG? boolean 调试标记
---@field _DATAGRAMSIZE integer UDP 默认 datagram 大小
---@field _SETSIZE integer select fd set 大小
---@field _SOCKETINVALID integer 无效 socket fd
---@field dns socket_core_dns* DNS 工具
---@type socket_core*
local M = {}

--- 创建 TCP socket。
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg 错误信息
function M.tcp() end

--- 创建 IPv4 TCP socket。
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg 错误信息
function M.tcp4() end

--- 创建 IPv6 TCP socket。
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg 错误信息
function M.tcp6() end

--- 创建 UDP socket。
---@return socket_core_udp*? client UDP socket
---@return string? errMsg 错误信息
function M.udp() end

--- 创建 IPv4 UDP socket。
---@return socket_core_udp*? client UDP socket
---@return string? errMsg 错误信息
function M.udp4() end

--- 创建 IPv6 UDP socket。
---@return socket_core_udp*? client UDP socket
---@return string? errMsg 错误信息
function M.udp6() end

--- 连接 TCP 服务。
---@param address string 远端地址
---@param port integer 远端端口
---@param laddress? string 本地地址
---@param lport? integer 本地端口
---@param family? 'inet'|'inet6' 地址族
---@return socket_core_tcp*? client TCP socket
---@return string? errMsg 错误信息
function M.connect(address, port, laddress, lport, family) end

--- 等待 socket 可读或可写。
---@param recvt? table 可读 socket 列表
---@param sendt? table 可写 socket 列表
---@param timeout? number 超时秒数
---@return table readable 可读列表
---@return table writable 可写列表
---@return string? errMsg 错误信息
function M.select(recvt, sendt, timeout) end

--- 当前时间。
---@return number time 秒级时间
function M.gettime() end

--- 延迟指定秒数。
---@param seconds number 秒数
function M.sleep(seconds) end

--- 创建错误保护函数。
---@param finalizer? function 收尾函数
---@return function try try 函数
function M.newtry(finalizer) end

--- 保护函数调用。
---@param func function 函数
---@return function protected 保护后的函数
function M.protect(func) end

--- 跳过前 n 个返回值。
---@param count integer 跳过数量
---@param ... any 值
---@return any ... 剩余值
function M.skip(count, ...) end

--- 卸载底层 socket 库。
function M.__unload() end

--- 查询主机名。
---@return string hostname 主机名
function socket_core_dns.gethostname() end

--- 主机名转 IP。
---@param name string 主机名
---@return string? ip IP 地址
---@return table|string? resolved 解析信息或错误信息
function socket_core_dns.toip(name) end

--- IP 转主机名。
---@param address string IP 地址
---@return string? name 主机名
---@return table|string? resolved 解析信息或错误信息
function socket_core_dns.tohostname(address) end

--- 查询地址信息。
---@param host string 主机名或 IP 地址
---@return table? info 地址信息列表
---@return string? errMsg 错误信息
function socket_core_dns.getaddrinfo(host) end

--- 反查地址和服务名。
---@param address string IP 地址
---@param port? integer 端口
---@return string? host 主机名
---@return string? service 服务名
function socket_core_dns.getnameinfo(address, port) end

--- 获取 socket 地址族。
---@return 'inet'|'inet6'|string family 地址族
function socket_core_tcp:getfamily() end

--- 获取底层 fd。
---@return integer fd 文件描述符
function socket_core_tcp:getfd() end

--- 替换底层 fd。
---@param fd integer 文件描述符
---@return integer? ok 成功时返回 1
---@return string? errMsg 错误信息
function socket_core_tcp:setfd(fd) end

--- 查询缓冲区是否有未读数据。
---@return boolean dirty 是否有未读数据
function socket_core_tcp:dirty() end

--- 获取超时设置。
---@return number? block 单次操作超时
---@return number? total 总超时
function socket_core_tcp:gettimeout() end

--- 获取传输统计。
---@return integer received 已接收字节数
---@return integer sent 已发送字节数
---@return number age 创建后秒数
function socket_core_tcp:getstats() end

--- 设置传输统计。
---@param received? integer 已接收字节数
---@param sent? integer 已发送字节数
---@param age? number 创建后秒数
---@return integer? ok 成功时返回 1
function socket_core_tcp:setstats(received, sent, age) end

--- 关闭单向或双向传输。
---@param mode? socket_shutdown_mode 关闭方向
---@return integer? ok 成功时返回 1
---@return string? errMsg 错误信息
function socket_core_tcp:shutdown(mode) end

--- 获取 socket 地址族。
---@return 'inet'|'inet6'|string family 地址族
function socket_core_udp:getfamily() end

--- 获取底层 fd。
---@return integer fd 文件描述符
function socket_core_udp:getfd() end

--- 替换底层 fd。
---@param fd integer 文件描述符
---@return integer? ok 成功时返回 1
---@return string? errMsg 错误信息
function socket_core_udp:setfd(fd) end

--- 查询 socket 是否有未读数据。
---@return boolean dirty 是否有未读数据
function socket_core_udp:dirty() end

--- 获取超时设置。
---@return number? block 单次操作超时
---@return number? total 总超时
function socket_core_udp:gettimeout() end

--- 获取 socket 选项。
---@param option string 选项名
---@return any value 选项值
---@return string? errMsg 错误信息
function socket_core_udp:getoption(option) end

return M
