websocket - websocket 客户端 副本

一、概述

WebSocket 是 HTML5 下一种新的协议（本质上是一个基于 TCP 的协议），主要解决传统 HTTP 协议在 “实时通信” 场景下的效率问题。它实现了浏览器与服务器之间的全双工通信，能够节省服务器资源和带宽，达到实时通讯的目的。WebSocket 协议通过握手机制，允许客户端和服务器之间建立一个类似 TCP 的连接，从而方便它们之间的通信，适用于需要实时数据交换的应用场景，如实时聊天、实时游戏、股票行情等。

WebSocket 底层基于 TCP 连接，支持加密 TCP（wss）和非加密 TCP（ws）。

任何通信失败都将断开连接，如果开启了自动重连，那么间隔 N 秒后会开始自动重连；

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/websocket；

Websocket 客户端

--[[
本核心示例的的业务逻辑为：
1、创建并启动一个基础task，task名称为"mqtt_client_task_func"，在task的任务处理函数内创建mqtt客户端和连接mqtt服务器，并执行一些相关操作；2、创建并启动一个基础task，task名称为"mqtt_data_report_task_func"，在task的任务处理函数内定时发布数据；
]]

-- 加载WebSocket client数据接收功能模块
local websocket_receiver = require "websocket_receiver"
-- 加载WebSocket client数据发送功能模块
local websocket_sender = require "websocket_sender"

-- WebSocket服务器地址和端口
-- 这里使用的地址和端口，会不定期重启或维护，仅能用作测试用途，不可商用，说不定哪一天就关闭了
-- 用户开发项目时，替换为自己的商用服务器地址和端口
-- 加密TCP链接 wss 表示加密
local SERVER_URL = "wss://echo.airtun.air32.cn/ws/echo"
-- 这是另外一个测试服务, 能响应websocket的二进制帧
--local SERVER_URL = "ws://echo.airtun.air32.cn/ws/echo2"

-- websocket_main的任务名
local TASK_NAME = websocket_sender.TASK_NAME_PREFIX.."main"

-- WebSocket client的事件回调函数
local function websocket_client_event_cbfunc(ws_client, event, data, fin, opcode)
    log.info("WebSocket事件回调", ws_client, event, data, fin, opcode)

    -- WebSocket连接成功
    if event == "conack" then
        sysplus.sendMsg(TASK_NAME, "WEBSOCKET_EVENT", "CONNECT", true)
        -- 连接成功，通知网络环境检测看门狗功能模块进行喂狗
        sys.publish("FEED_NETWORK_WATCHDOG")

    -- 接收到服务器下发的数据
    -- data：string类型，表示接收到的数据
    -- fin：number类型，1表示是最后一个数据包，0表示还有后续数据包
    -- opcode：number类型，表示数据包类型（1-文本，2-二进制）
    elseif event == "recv" then
        -- 对接收到的数据处理
        websocket_receiver.proc(data, fin, opcode)

    -- 发送成功数据
    -- data：number类型，表示发送状态（通常为nil或0）
    elseif event == "sent" then
        log.info("WebSocket事件回调", "数据发送成功，发送确认")
        -- 发送消息通知 websocket sender task
        sysplus.sendMsg(websocket_sender.TASK_NAME, "WEBSOCKET_EVENT", "SEND_OK", data)

    -- 服务器断开WebSocket连接
    elseif event == "disconnect" then
        -- 发送消息通知 websocket main task
        sysplus.sendMsg(TASK_NAME, "WEBSOCKET_EVENT", "DISCONNECTED", false)

    -- 严重异常，本地会主动断开连接
    -- data：string类型，表示具体的异常，有以下几种：
    --       "connect"：tcp连接失败
    --       "tx"：数据发送失败
    --       "other"：其他异常
    elseif event == "error" then
        if data == "connect" then
            -- 发送消息通知 websocket main task，连接失败
            sysplus.sendMsg(TASK_NAME, "WEBSOCKET_EVENT", "CONNECT", false)
        elseif data == "other" or data == "tx" then
            -- 发送消息通知 websocket main task，出现异常
            sysplus.sendMsg(TASK_NAME, "WEBSOCKET_EVENT", "ERROR")
        end
    end
end

-- websocket main task 的任务处理函数
local function websocket_client_main_task_func()
    local ws_client
    local result, msg

    while true do
        -- 如果当前时间点设置的默认网卡还没有连接成功，一直在这里循环等待
        while not socket.adapter(socket.dft()) do
            log.warn("WebSocket主任务", "等待网络就绪", socket.dft())
            -- 在此处阻塞等待默认网卡连接成功的消息"IP_READY"
            -- 或者等待1秒超时退出阻塞等待状态;
            -- 注意：此处的1000毫秒超时不要修改的更长；
            -- 因为当使用exnetif.set_priority_order配置多个网卡连接外网的优先级时，会隐式的修改默认使用的网卡
            -- 当exnetif.set_priority_order的调用时序和此处的socket.adapter(socket.dft())判断时序有可能不匹配
            -- 此处的1秒，能够保证，即使时序不匹配，也能1秒钟退出阻塞状态，再去判断socket.adapter(socket.dft())
            sys.waitUntil("IP_READY", 1000)
        end

        -- 检测到了IP_READY消息
        log.info("WebSocket主任务", "收到网络就绪消息", socket.dft())

        -- 清空此task绑定的消息队列中的未处理的消息
        sysplus.cleanMsg(TASK_NAME)

        -- 创建WebSocket client对象
        ws_client = websocket.create(nil, SERVER_URL)
        -- 如果创建WebSocket client对象失败
        if not ws_client then
            log.error("WebSocket主任务", "WebSocket创建失败")
            goto EXCEPTION_PROC
        end

        -- 设置自定义请求头
        --如果有需要，根据自己的实际需求，在此处配置请求头并打开注释。
        --if ws_client.headers then
           --ws_client:headers({Auth="Basic ABCDEGG"})
        --end

        -- 注册WebSocket client对象的事件回调函数
        ws_client:on(websocket_client_event_cbfunc)

        -- 连接server
        result = ws_client:connect()
        -- 如果连接server失败
        if not result then
            log.error("WebSocket主任务", "WebSocket连接失败")
            goto EXCEPTION_PROC
        end

        -- 连接、断开连接、异常等各种事件的处理调度逻辑
        while true do
            -- 等待"WEBSOCKET_EVENT"消息
            msg = sysplus.waitMsg(TASK_NAME, "WEBSOCKET_EVENT")
            log.info("WebSocket主任务等待消息", msg[2], msg[3], msg[4])

            -- connect连接结果
            -- msg[3]表示连接结果，true为连接成功，false为连接失败
            if msg[2] == "CONNECT" then
                -- WebSocket连接成功
                if msg[3] then
                    log.info("WebSocket主任务", "连接成功")
                    -- 通知websocket sender数据发送应用模块的task，WebSocket连接成功
                    sysplus.sendMsg(websocket_sender.TASK_NAME, "WEBSOCKET_EVENT", "CONNECT_OK", ws_client)
                -- WebSocket连接失败
                else
                    log.info("WebSocket主任务", "连接失败")
                    -- 退出循环，发起重连
                    break
                end

            -- 需要主动关闭WebSocket连接
            -- 用户需要主动关闭WebSocket连接时，可以调用sysplus.sendMsg(TASK_NAME, "WEBSOCKET_EVENT", "CLOSE")
            elseif msg[2] == "CLOSE" then
                -- 主动断开WebSocket client连接
                ws_client:disconnect()
                -- 发送disconnect之后，此处延时1秒，给数据发送预留一点儿时间
                sys.wait(1000)
                break

            -- 被动关闭了WebSocket连接
            -- 被网络或者服务器断开了连接
            elseif msg[2] == "DISCONNECTED" then
                break

            -- 出现了其他异常
            elseif msg[2] == "ERROR" then
                break
            end
        end

        -- 出现异常
        ::EXCEPTION_PROC::

        -- 清空此task绑定的消息队列中的未处理的消息
        sysplus.cleanMsg(TASK_NAME)

        -- 通知websocket sender数据发送应用模块的task，WebSocket连接已经断开
        sysplus.sendMsg(websocket_sender.TASK_NAME, "WEBSOCKET_EVENT", "DISCONNECTED")

        -- 如果存在WebSocket client对象
        if ws_client then
            -- 关闭WebSocket client，并且释放WebSocket client对象
            ws_client:close()
            ws_client = nil
        end

        -- 5秒后跳转到循环体开始位置，自动发起重连（与MQTT保持一致）
        sys.wait(5000)
    end
end

--创建并且启动一个task
sysplus.taskInitEx(websocket_client_main_task_func, TASK_NAME)

三、常量详解

核心库常量是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

websocket 核心库没有常量。

四、函数详解

4.1 wsc:debug(onoff)

功能 配置是否打开 debug 信息，即控制 websocket 客户端是否输出调试信息

注意事项

1. 必须传入布尔类型参数 onoff（true 表示打开调试，false 表示关闭调试）；
2. 建议开发调试阶段可打开，方便查看 mqtt 通信的详细过程。调试结束后应关闭，以减少不必要的日志输出；

参数 onoff

参数含义：是否打开debug信息，true表示打开调试，false表示关闭调试；
数据类型：boolean；
取值范围：true/false；
是否必选：必须传入此参数；
注意事项：必须是布尔类型（true/false）；
参数示例：-- 如下方所示，传入值为true，表示打开调试；
         wsc:debug(true)  -- 打开调试信息
         wsc:debug(false) -- 关闭调试信息

返回值 该接口无返回值，只需调用该接口执行相关操作，无需处理返回结果；

如果一定要把接口调用的结果赋值给一个变量，则这个变量就是一个 nil 值；

示例

-- 如下方所示，传入值为true，表示打开调试；
 wsc:debug(true)  
 -- 如下方所示，传入值为true，表示关闭调试；
 wsc:debug(false)

4.2 websocket.create(adapter, url, keepalive, use_ipv6)

功能 WebSocket 客户端创建

参数

adapter

**参数含义**：适配器序号，如果不填，会选择平台自带的方式，然后是最后一个注册的适配器，可选值请查阅socket库的常量表；
**数据类型**：number/nil
**取值范围**：number类型时，取值范围参考socket api中的常量详解；
**是否必选**：可选传入此参数；
**注意事项**：如果没有传入此参数，内核固件会自动选择当前时间点其他功能模块设置的默认网卡。
除非你WebSocket请求时，一定要使用某一种网卡，才设置此参数。
如果没什么特别要求，不要设置此参数，使用系统中设置的默认网卡即可。
**参数示例**：
-- 如下方所示，这是普通TCP连接的写法，第一个参数不填时默认为平台自带方式或最后注册的适配器；
websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
 -- 如下方所示，这是普通TCP连接的写法，查阅socket库的常量表，将需要的常量填到第一个参数的位置；
websocket.create(socket.LWIP_GP, "ws://echo.airtun.air32.cn/ws/echo")

url

**参数含义**：WebSocket服务器地址，包括协议、域名或IP、端口和路径。
**数据类型**：string
**是否必选**：必选
**注意事项**：URL必须包含协议部分，支持ws和wss。wss表示使用TLS加密连接。
**参数示例**：
-- 如下方所示，这是普通TCP连接的写法
wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
-- 如下方所示，这是加密TCP连接的写法
wsc = websocket.create(nil, "wss://echo.airtun.air32.cn/ws/echo")

keepalive

**参数含义：**心跳间隔时间，单位为秒**
****数据类型：**number**
****取值范围：**大于 0 的整数**
****是否必选：**可选**
****注意事项：**不填时默认 60 秒。最小值限制为30秒（若传入小于30的值，会被强制设为30秒）。
         没有限制最大值，但不建议设置过长的心跳间隔。
参数示例：
-- 如下方所示，这是普通TCP连接的写法，第三个参数不填时表示默认60秒心跳
websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
--- 如下方所示，这是加密TCP连接的写法，设置120秒心跳
 websocket.create(nil,"wss://air32.cn/abc",120)

use_ipv6

**参数含义**：是否使用 IPv6 协议，true表示使用ipv6协议，false表示使用ipv4协议，不填时默认 false（使用 IPv4）；
**数据类型**：boolean
**是否必选**：可选
**注意事项**：ipv6功能需要设备和网络环境支持，否则即使设置为true也无法连接；
**返回值**：成功时返回 WebSocket 客户端对象，失败时返回 nil
**参数示例：**
-- 如下方所示，这是普通TCP连接的写法，第四个参数不填时为使用ipv4协议；
websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
-- 如下方所示，这是加密TCP连接的写法，第四个参数填true时，为使用IPv6协议；
websocket.create(nil, "wss://echo.airtun.air32.cn/ws/echo", 180, true)

返回值

local wsc = websocket.create(adapter, url, keepalive, use_ipv6)

有一个返回值 wsc

wsc

**含义说明：**WebSocket 客户端实例对象
**数值类型：**userdata/nil
**取值范围：**成功时返回 userdata，失败时返回 nil
**注意事项：**有返回 nil 的情况，需做好对应逻辑处理

示例：

-- 普通TCP连接，使用默认适配器和IPv4
wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")

-- 普通TCP连接，指定适配器和IPv4，设置心跳为120秒
wsc = websocket.create(socket.LWIP_GP, "ws://echo.airtun.air32.cn/ws/echo", 120, false)

-- 加密TCP连接，使用默认适配器和IPv4
wsc = websocket.create(nil, "wss://echo.airtun.air32.cn/ws/echo")

-- 普通TCP连接，使用默认适配器和IPv6协议，设置心跳为120秒
wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo", 120, true)

4.3 wsc:on(cb)

功能 注册 WebSocket 回调函数。

参数

cb

**参数含义**：websocket回调函数，回调函数的格式为：
        function callback (ws_client, event, data, fin, opcode)
            -- websocket_client：userdata类型，WebSocket客户端实例对象
            -- event：string类型，事件类型标识符
            -- data：多种类型，事件相关数据，具体内容取决于事件类型
            -- fin：number类型，是否为最后一帧，仅对"recv"事件有效
            -- opcode：number类型，操作码，表示数据包类型，如1表示文本帧，2表示二进制帧等，仅对"recv"事件有效
          log.info("websocket", "event", event, data, fin, opcode)
       end)

       该回调函数接收ws_client, event, data, fin, opcode五个参数；

       --参数含义：WebSocket 客户端实例对象
       --数据类型：userdata
       --取值范围：有效的 WebSocket 客户端对象
       --必选：是
       --注意事项：此参数指向当前触发事件的 WebSocket 客户端实例，可用于在回调中调用该实例的方法  
        ws_client


        --**参数含义**：事件类型，表示当前发生的 WebSocket 事件
**       --数据类型**：string
**       --取值范围**：可能的取值包括：
         --"conack": 连接服务器成功，已经收到 WebSocket 协议头部信息，通信已建立
         --"recv": 收到服务器下发的信息
         --"sent": send 函数发送的消息，服务器在 TCP 协议层已确认收到
         --"disconnect": 服务器连接已断开
         --"error": 发生错误
**       --是否必选**：是
**       --注意事项**：应根据不同的事件类型执行相应的处理逻辑
       event


**       --参数含义**：事件相关数据，具体内容取决于事件类型
**       --数据类型**：多种类型（string/number/nil）
**       --取值范围**：根据事件类型不同而不同：
         --"conack": 无数据（通常为 nil）
         --"recv": 字符串类型，表示接收到的数据内容
         --"sent": 数值类型，表示发送状态（通常为 nil 或 0）
         --"disconnect": 数值类型，表示错误码
         --"error": 字符串类型，表示具体的错误类型
**       --是否必选**：是（但某些事件可能为 nil）
**       --注意事项**：需要根据事件类型来解析和处理 data 参数
       data


       --**参数含义**：是否为最后一帧，仅对 "recv" 事件有效
**       --数据类型**：number
**       --取值范围**：0 或 1
         --0: 表示还有后续数据包
         --1: 表示是最后一个数据包
**       --是否必选**：是（但仅对 "recv" 事件有意义）
**       --注意事项**：用于处理分帧传输的数据，当 fin=0 时需要缓存数据直到收到 fin=1 的帧
       fin


       --**参数含义**：操作码，表示数据包类型，仅对 "recv" 事件有效
**       --数据类型**：number
**       --取值范围**：
         --0: 中间数据
         --1: 文本帧
         --2: 二进制帧
**       --注意事项**：---因为lua并不区分文本和二进制数据, 所以optcode通常可以无视
       opcode

数据类型：function
取值范围：回调函数本身无取值范围这一说法；
是否必选：必须

返回值 该接口无返回值，只需调用该接口执行相关操作，无需处理返回结果；

示例

-- 如下方所示，这是注册WebSocket客户端的事件回调函数写法；
function websocket_client_cbfunc(websocket_client, event, data, fin, opcode)
    -- 每次进回调函数都打印一次这五个参数；
    log.info("websocket_client_cbfunc", websocket_client, event, data, fin, opcode)

    -- 连接服务器成功，已经收到WebSocket协议头部信息，通信已建立；
    if event == "conack" then
        log.info("websocket_client_cbfunc", "conack", "连接成功")
        -- 此处为用户代码，可在此处发送echo命令等；
        websocket_client:send(json.encode({action="echo", device_id="test_device"}))

    -- 收到服务器下发的信息；
    -- data：字符串类型，表示接收到的数据内容；
    -- fin：数值类型，表示是否为最后一帧（0表示还有后续，1表示最后一帧）；
    -- opcode：数值类型，表示数据包类型（1-文本，2-二进制）；
    elseif event == "recv" then
        log.info("websocket_client_cbfunc", "recv", "收到数据", "内容:", data, "是否为最后一帧:", fin, "操作码:", opcode)
        -- 处理分帧数据
        if fin == 0 then
            log.info("websocket_client_cbfunc", "recv", "收到部分数据，等待后续")
        else
            log.info("websocket_client_cbfunc", "recv", "收到完整数据")
            -- 尝试解析JSON
            local json_data, result, errinfo = json.decode(data)
            if result then
                if json_data.action == "echo_ack" then
                    log.info("websocket_client_cbfunc", "recv", "收到echo响应", json_data.msg)
                end
            end
        end

    -- send函数发送的消息，服务器在TCP协议层已确认收到；
    -- data：数值类型，表示发送状态（通常为nil或0）；
    elseif event == "sent" then
        log.info("websocket_client_cbfunc", "sent", "发送消息成功", "状态:", data)

    -- 服务器连接已断开；
    -- data：数值类型，表示错误码；
    elseif event == "disconnect" then
        log.info("websocket_client_cbfunc", "disconnect", "连接断开", "错误码:", data)

    -- 严重异常，本地会主动断开连接；
    -- data：字符串类型，表示具体的异常，有以下几种类型：
    --      "connect"：表示TCP连接失败；
    --      "tx"：表示数据发送失败；
    --      "other"：表示其他异常情况；
    elseif event == "error" then
        log.info("websocket_client_cbfunc", "error", "发生异常错误")
        if data == "connect" then
            log.info("websocket_client_cbfunc", "error", "TCP连接失败")
        elseif data == "tx" then
            log.info("websocket_client_cbfunc", "error", "数据发送失败")
        else
            log.info("websocket_client_cbfunc", "error", "其他错误", data)
        end
    end
end

-- 注册WebSocket事件回调函数接口，websocket_client_cbfunc为回调函数；
wsc:on(websocket_client_cbfunc)

4.4 wsc:connect()

功能 连接服务器。

参数 无

返回值

local connect_result = ws_client:connect()

有一个返回值 local connect_result

含义说明：连接请求是否发起成功
数值类型：boolean
取值范围：true/false
注意事项：本函数仅代表发起成功, 该接口仅表示连接请求是否成功发送，不代表已与websocket服务器建立实际连接；
         实际连接结果需要通过wsc:on(cb)中注册的cb回调函数判断

示例

wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
wsc:on(websocket_callback)
local result = wsc:connect()
if result then
    log.info("websocket", "连接请求已发起")
else
    log.error("websocket", "连接请求失败")
end

4.5 wsc:autoreconn(reconnect, reconnect_time)

功能

用于配置 websocket 客户端的自动重连功能，包括启用/禁用自动重连以及设置重连周期；

注意事项

1. 该接口仅控制自动重连的配置，不直接执行重连操作；
2. 重连功能仅在连接断开后生效，不会主动尝试断开现有连接；
3. 如果项目中使用多网卡功能，一定不要使用此接口，否则内核固件在自动重连时，可能会使用错误的网卡，导致无法上网

参数

reconnect

**参数含义**：是否自动重连
**数据类型**：boolean
**取值范围**：true/false
**是否必选**：必须
**注意事项**：设置为 true 时开启自动重连
         建议在调用wsc:connect()前配置该参数，以确保连接建立前重连策略已正确设置；
**参数示例**：
-- 如下方所示，启用websocket客户端的自动重连功能；
wsc:autoreconn(true)
-- 如下方所示，禁用websocket客户端的自动重连功能；
wsc:autoreconn(false)

reconnect_time

**参数含义**：自动重连周期，单位毫秒
**数据类型**：number
**取值范围**：默认值为3000ms；
**是否必选**：可选传入此参数，若不填默认为3000ms
**注意事项**：参数单位为毫秒（ms），配置时需注意时间单位转换；         
         可以单独配置该参数而不改变自动重连开关状态（例如仅调整重连周期，不改变是否自动重连）；
**参数示例**：
        -- 如下方所示，启用自动重连功能，默认重连周期为3000ms；         
        wsc:autoreconn(true)         
        -- 如下方所示，启用自动重连功能，设置重连周期为5000ms；         
        wsc:autoreconn(true, 5000)                 
        -- 如下方所示，不改变自动重连功能的状态，仅调整重连周期为4000ms；         
        wsc:autoreconn(nil, 4000)

返回值

该接口无返回值，只需调用该接口执行相关操作，无需处理返回结果；

如果一定要把接口调用的结果赋值给一个变量，则这个变量就是一个 nil 值；

示例

-- 如下方所示，启用自动重连功能，默认重连周期为3000ms；         
wsc:autoreconn(true)         
-- 如下方所示，启用自动重连功能，设置重连周期为5000ms；         
wsc:autoreconn(true, 5000)         
-- 如下方所示，不改变自动重连功能的状态，仅调整重连周期为4000ms；         
wsc:autoreconn(nil, 4000)

4.6 wsc:send(data, fin, opt)

功能 发送数据。

注意事项

1. 发送的数据必须是字符串类型
2. 分段发送时，最后一帧的 fin 参数必须设置为 1

参数

data

**参数含义**：待发送的数据
**数据类型**：string
**取值范围**：无限制
**是否必选**：必须
**注意事项**：必须是字符串类型
**参数示例**：
wsc:send("hello world")

fin

**参数含义**：是否为最后一帧
**数据类型**：number
**取值范围**：0/1
**是否必选**：可选
**注意事项**：不填时默认 1（单帧发送）
**参数示例**：
wsc:send("hello world", 0)  -- 还有后续帧
wsc:send("hello world", 1)  -- 最后一帧

opt

**参数含义**：操作码
**数据类型**：number
**取值范围**：0-2
**是否必选**：可选
**注意事项**：不填时默认 0（文本帧）
**参数示例**：
wsc:send("hello", 1, 0)  -- 文本帧
wsc:send("binary_data", 1, 2)  -- 二进制帧

返回值

• 含义说明：发送请求是否成功
• 数值类型：boolean
• 取值范围：true/false
• 注意事项：仅代表发送请求是否成功，实际发送结果需要通过 wsc:on(cb)中注册的 cb 回调函数判断
• 示例：

-- 简单发送文本数据
wsc:send("hello world")

-- 分段发送数据
wsc:send("hello", 0)  -- 非最后一帧
wsc:send(" ", 0)      -- 非最后一帧
wsc:send("hello world", 1)  -- 最后一帧

-- 发送二进制数据
wsc:send("binary_data", 1, 2)

4.7 wsc:close()

功能 关闭 WebSocket 连接。

注意事项

1. 关闭后资源释放无法再使用

参数 无

返回值 无返回值

示例

wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")
-- ... 使用WebSocket ...
wsc:close()  -- 关闭连接

4.8 wsc:ready()

功能 检查 WebSocket 客户端是否就绪（是否已成功连接到 websocket 服务器）；

注意事项

1. 该接口仅检查客户端的内部状态标记，不进行实际的网络连通性测试；
2. 返回 true 仅表示客户端当前处于连接状态，不保证网络连接一定稳定；
3. 即使返回 true，后续的操作仍有可能因网络问题失败，建议做好错误处理；

参数 无

返回值

local websocket_ready_result = wsc:ready()

有一个返回值 websocket_ready_result

websocket_ready_result

**含义说明**：WebSocket 客户端是否就绪
**数值类型**：boolean
**取值范围**：true/false
**注意事项**：接口返回值仅检查客户端的内部状态标记，不进行实际的网络连通性测试；
         返回true仅表示客户端当前认为自己处于连接状态，不保证网络连接一定稳定；
         即使返回true，后续的发布/订阅操作仍有可能因网络问题失败，建议做好错误处理；

示例

-- 如下方所示，为一个最基本的wsc:ready()接口的写法；
local websocket_ready_result = wsc:ready()

-- 判断WebSocket客户端是否已就绪
if websocket_ready_result then
    log.info("WebSocket 客户端已就绪")
    -- 用户处理代码
    wsc:send("hello world")
else
    log.info("WebSocket 客户端未就绪，正在尝试重连...")
    -- 执行重连操作
end

4.9 wsc:headers(headers)

功能 设置自定义请求头。

注意事项

1. 如果有需要，根据自己的实际需求，在此处配置请求头

参数

headers

**参数含义**：请求头信息
**数据类型**：table/string
**取值范围**：table 或格式化的字符串
**是否必选**：必须
**注意事项**：如果是 table 类型，格式为 {key1=value1, key2=value2}
**参数示例**：
-- table形式
wsc:headers({Auth="Basic ABCDEFGG"})
-- 字符串形式
wsc:headers("Auth: Basic ABCDERG\r\n")

返回值 无返回值

示例

-- 创建WebSocket客户端
wsc = websocket.create(nil, "ws://echo.airtun.air32.cn/ws/echo")

--table和string两种方式使用其中一种即可
-- table形式的headers设置示例
wsc:headers({
    Auth = "Basic ABCDEGG",
    CustomHeader = "custom_value",
    UserAgent = "LuatOS-WebSocket-Client/1.0"
})

-- 字符串形式的headers设置示例
--wsc:headers("Auth: Basic ABCDEGG\r\nCustomHeader: custom_value\r\nUserAgent: LuatOS-WebSocket-Client/1.0\r\n")

-- 连接服务器
wsc:connect()

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 websocket 核心库。