WebSocket
【E2EE文档】

WebSocket

E2EE提供了WebSocket的支持。

什么是WebSocket?

WebSocket协议是基于TCP的一种新的网络协议。它实现了浏览器与服务器全双工(full-duplex)通信——可以通俗的解释为服务器主动发送信息给客户端。

WebSocket首次在HTML5规范中被引用为TCP连接,作为基于TCP的套接字API的占位符。[1] WebSocket通信协议于2011年被IETF定为标准RFC 6455,并被RFC7936所补充规范。

下载示例:WebSocket聊天室

本章节目录:

  1. 使用WebSocket服务器
  2. WebSocket功能
  3. 启用TLS(wss)

E2EE的WebSocket服务器特性

  • 全面支持 RFC6455 规范
  • 支持订阅通道和组播
  • 支持给客户绑定任意属性
  • 支持TLS(wss)
  • 线程安全

1. 使用WebSocket服务器

使用WebSocket服务器流程:

  • 创建WebSocket服务器变量
  • 初始化服务器
  • 启动WebSocket服务器
  • 对用户发送消息进行处理

1.1 创建WebSocket服务器变量

.程序集变量 WS服务器, WebSocket服务器

1.2 初始化服务器

WS服务器.初始化 (服务器, 9002, , , &WS_收到消息)

WebSocket服务器初始化函数原型

WebSocket服务器.初始化([网站服务器], 整数型 端口, [子程序指针 客户进入事件], [子程序指针 客户退出事件], [子程序指针 收到消息事件])

网站服务器:绑定到网站服务器。类型为“网站服务器(JHTTPServer)”,可以被省略。

绑定的主要作用是同步输出日志到服务器日志中,允许为空,当为空的时候错误时将无日志内容输出。网页提交的文本数据和发送给客户的文本数据不会被自动编码。

端口:绑定到的目标端口。可以被省略。如果不设置则默认端口为9002。

客户进入事件:客户进入时触发的子程序。可以被省略。

格式:<无返回值> 客户进入事件([整数] 客户句柄)。

客户退出事件:客户退出时触发的子程序。可以被省略。

格式:<无返回值> 客户退出事件([整数] 客户句柄)。

收到消息事件:收到客户发送数据时触发的子程序。可以被省略。

格式:<无返回值> 收到消息事件([整数] 客户句柄, [整数] 消息类型, [整数] 消息句柄)。

消息类型可以参考“WS类型_”开头常量,消息内容可以通过 WS服务器.取回消息(消息句柄) 获取到(主要是易语言子程序不支持字节集)。

进入/退出/收到消息事件子程序模板

.版本 2
.支持库 e2ee

.子程序 WS_客户进入
.参数 客户句柄, 整数型


.子程序 WS_客户退出
.参数 客户句柄, 整数型


.子程序 WS_收到消息
.参数 客户句柄, 整数型
.参数 消息类型, 整数型
.参数 消息句柄, 整数型
.局部变量 消息, 文本型

.如果真 (消息类型 = #WS类型_文本_Text)
    消息 = WS服务器.取回消息文本 (消息句柄)
.如果真结束

1.3 启动WebSocket服务器

执行服务器对象的 启动() 方法

WS服务器.启动 ()

1.4 对用户发送消息进行处理

初始化时注册“收到消息事件”。对用户提交的信息进行处理。

示例:

.版本 2
.支持库 e2ee
.支持库 spec

.子程序 WS_收到消息
.参数 客户句柄, 整数型
.参数 消息类型, 整数型
.参数 消息句柄, 整数型
.局部变量 消息, 存取键值表
.局部变量 类型, 整数型
.局部变量 房间, 整数型
.局部变量 昵称, 文本型
.局部变量 发送消息, 文本型

.如果真 (消息类型 = #WS类型_文本_Text)
    .如果真 (消息.从JSON载入 (到文本 (WS服务器.取回消息文本 (消息句柄))))
        类型 = 消息.取整数 (“编号”)
        ' // 取回房间和昵称信息
        .如果 (类型 = 9)
            ' // 执行用户登陆
            房间 = 消息.取整数 (“房间”)
            昵称 = HTML关键字编码 (消息.取文本 (“昵称”))
            .判断开始 (房间 ≠ 1 且 房间 ≠ 2)  ' // 房间不对
                WS服务器.发送文本 (客户句柄, 创建错误 (客户句柄, -9, “请选择正确的聊天室”))
                WS服务器.关闭客户 (客户句柄)
            .判断 (取文本长度 (昵称) = 0)  ' // 昵称不对
                WS服务器.发送文本 (客户句柄, 创建错误 (客户句柄, -9, “昵称不能为空”))
                WS服务器.关闭客户 (客户句柄)
            .判断 (取文本长度 (昵称) > 32)  ' // 昵称不对
                WS服务器.发送文本 (客户句柄, 创建错误 (客户句柄, -9, “昵称不能大于32个字符”))
                WS服务器.关闭客户 (客户句柄)
            .默认
                ' // 成功登陆
                WS服务器.设置属性 (客户句柄, “登录”, “1”)
                WS服务器.设置属性 (客户句柄, “房间”, 到文本 (房间))
                WS服务器.设置属性 (客户句柄, “昵称”, 昵称)
                WS服务器.设置通道 (客户句柄, 房间)
                WS服务器.发送文本 (客户句柄, 创建成功 (客户句柄, 9, “登录成功”, 昵称))
                WS服务器.发送通道文本 (房间, 创建成功 (0, 109, 创建文本 (“欢迎[{1}]进入房间!”, 昵称), “系统消息”))
                调试输出 (WS服务器.取客户列表 (0))
            .判断结束
            返回 ()
        .否则
            .如果真 (WS服务器.获取属性 (客户句柄, “登录”) ≠ “1”)
                WS服务器.发送文本 (客户句柄, 创建错误 (客户句柄, -9, “您还没有登录”))
                WS服务器.关闭客户 (客户句柄)
                返回 ()
            .如果真结束
            房间 = 到数值 (WS服务器.获取属性 (客户句柄, “房间”))
            昵称 = WS服务器.获取属性 (客户句柄, “昵称”)
        .如果结束

        ' // 通过类型执行操作
        .判断开始 (类型 = 1)  ' // 发送消息
            发送消息 = HTML关键字编码 (消息.取文本 (“内容”))
            .如果 (发送消息 = “”)
                WS服务器.发送文本 (客户句柄, 创建错误 (客户句柄, -1, “消息不能为空”))
                返回 ()
            .否则
                WS服务器.发送文本 (客户句柄, 创建成功 (客户句柄, 2, “发送成功”))
            .如果结束
            WS服务器.发送通道文本 (房间, 创建成功 (客户句柄, 1, 发送消息, 昵称))
        .默认

        .判断结束

    .如果真结束

.如果真结束

消息类型可以通过“#WS类型_”常量获取。

  • WS类型_文本_Text: 1
  • WS类型_字节集_Binary: 2
  • WS类型_指令关闭_Close: 8
  • WS类型_指令PING_Ping: 9
  • WS类型_指令PONG_Pong: 10
  • WS类型_续包_Continuation: 0

消息句柄消息内容的句柄,可通过下面的方式获取到:

  • WebSocket服务器.取回消息文本: 取回消息文本内容
  • WebSocket服务器.取回消息数据: 取回消息字节集内容

2. WebSocket功能

2.1 基础方法

初始化

  • 初始化: 初始化服务器。使用方法见上文。
  • 设置端口: 设置服务器端口。仅在服务器启动前设置有效。
  • 获取端口: 获取当前服务器端口。

服务器控制

  • 启动: 启动服务器。
  • 停止: 关闭服务器。

服务器状态

  • 是否运行中: 判断服务器是否在运行。
  • 取客户数: 获取客户数量。通道号为0取服务器所有客户数。
  • 取客户列表: 获取客户句柄数组。通道号为0取服务器所有客户句柄。

2.2 客户和消息处理

取回消息

取回消息的方法主要用于“收到消息事件”中:

  • 取回消息文本: 通过消息句柄取回消息内容。
  • 取回消息数据: 通过消息句柄取回消息字节集数据。

客户处理

  • 关闭客户: 关闭客户连接。
  • 是否在线: 判断客户是否在线。
  • 设置属性/获取属性: 给客户设置属性,属性信息将在客户端关闭后自动清空。属性的作用是方便存取跟客户关联的环境变量。
  • 设置通道/获取通道: 将客户绑定到抽象通道中。可通过通道号做为群组统一发送数据。相当于 订阅/发布 功能。

发送数据

  • 发送数据: 发送数据给客户。需要指定数据种类。
  • 发送文本: 发送文本给客户。类型为文本。
  • 发送字节集: 发送字节集给客户。类型为字节集(二进制数据)。

2.3 通道处理

通道处理

  • 取通道列表: 返回通道编号数组。
  • 是否存在通道: 判断通道是否存在。如果通道号为0则永远返回假。
  • 关闭通道: 关闭指定通道。通道内的所有客户都将被关闭。通道号不能为0(为0永远返回失败)。通道存在返回真,通道中如果没有客户,也会返回真。通道不存在返回假。

客户信息

  • 取客户数: 获取客户数量。
  • 取客户列表: 获取客户句柄数组。

发送数据

  • 发送通道数据: 发送数据给通道。需要指定数据种类。通道号为0则发送给所有用户。
  • 发送通道文本: 用通道作为分组发送文本。类型为文本。通道号为[0]时,为发送文本给所有客户端。
  • 发送通道字节集: 用通道作为分组发送字节集。类型为字节集(二进制数据)。通道号为[0]时,为发送字节集给所有客户端。

3. 启用TLS(wss)

要启用TLS功能非常简单,在初始化方法后加入 初始化WSS()方法即可。

WS服务器.初始化 (服务器, 9002, , &聊天服务器_WS_客户退出, &聊天服务器_WS_收到消息)
WS服务器.初始化WSS (真, , , , , )

初始化WSS() 方法说明:

<逻辑型> WebSocket服务器.初始化WSS()

初始化TLS安全传输层协议。务必在“初始化()”命令之后使用。用来设置是否启用WSS,和配置TLS的相关参数。

  • 使用网站配置: 逻辑型, 初始值为 真。确定是否使用和网站服务器同样的配置, 如果为真, 则后边的参数都不需要, 网站开启SSL则本服务器也开启, 网站没有开启则本服务器也不开启。如果网站开启了SSL, 所有相关证书等文件路径密码等直接使用网站本身的配置。
  • 是否启用WSS: 逻辑型。设置当前WebSocket是否启用安全传输协议, 可以被省略。
  • 密匙文件: 文本型。密匙文件路径, 可以被省略。
  • 证书文件: 文本型。证书文件路径, 可以被省略。
  • 签名文件: 文本型。签名文件路径。签名文件允许为空, 可以被省略。
  • 证书密码: 文本型。证书密码。密码允许为空, 可以被省略。

如果您的网站已经开启了HTTPS,并且wss请求域名和您的网站域名一致,则直接设置[使用网站配置]参数为真, 忽略其它配置即可。

启用TLS时,[签名文件]参数允许为空,证书没有设置密码时[证书密码]也可以为空。

详细的配置文件对应关系说明,请参考《创建网站和配置》的HTTPS配置(SSL)章节。