Swoole从入门到入土(17)——WebSocket服务器[成员函数与配置选项]

这一节，我们重点了解websocket server的成员函数以及相关的配置选项。

1、成员函数

push：向 WebSocket 客户端连接推送数据，长度最大不得超过 2M。

Swoole\WebSocket\Server->push(int $fd, string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, bool $finish = true): bool

// v4.4.12版本改为了flags参数
Swoole\WebSocket\Server->push(int $fd, string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, int $flags = SWOOLE_WEBSOCKET_FLAG_FIN): bool

$fd：客户端连接的 ID 【如果指定的 $fd 对应的 TCP 连接并非 WebSocket 客户端，将会发送失败】

$data：要发送的数据内容，Swoole 版本 >= v4.2.0 传入的 $data，如果是 Swoole\WebSocket\Frame 对象则其后续参数会被忽略

$opcode：指定发送数据内容的格式 【默认为WEBSOCKET_OPCODE_TEXT。发送二进制内容 $opcode 参数需要设置为 WEBSOCKET_OPCODE_BINARY】

 $finish：是否发送完成

注意：

自 v4.4.12 版本起，finish 参数（bool 型）改为 flags 参数（int 型）以支持 WebSocket 压缩，finish 对应 SWOOLE_WEBSOCKET_FLAG_FIN 值为 1，原有 bool 型值会隐式转换为 int 型，此改动向下兼容无影响。 此外压缩 flag 为 SWOOLE_WEBSOCKET_FLAG_COMPRESS。

exist：判断 WebSocket 客户端是否存在，并且状态为 Active 状态。

Swoole\WebSocket\Server->exist(int $fd): bool

返回值：连接存在，并且已完成 WebSocket 握手，返回 true；连接不存在或尚未完成握手，返回 false

注意：v4.3.0 以后，此 API 仅用于判断连接是否存在，请使用 isEstablished 判断是否为 WebSocket 连接。

pack：打包 WebSocket 消息。

Swoole\WebSocket\Server::pack(string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, bool $finish = true, bool $mask = false): string

// v4.4.12版本改为了flags参数
Swoole\WebSocket\Server::pack(string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, int $flags = SWOOLE_WEBSOCKET_FLAG_FIN): string

$data：消息内容

$opcode：指定发送数据内容的格式 【默认为WEBSOCKET_OPCODE_TEXT。发送二进制内容 $opcode 参数需要设置为 WEBSOCKET_OPCODE_BINARY】

$finish：帧是否完成 。自 v4.4.12 版本起，finish 参数（bool 型）改为 flags 参数（int 型）以支持 WebSocket 压缩，finish 对应 SWOOLE_WEBSOCKET_FLAG_FIN 值为 1，原有 bool 型值会隐式转换为 int 型，此改动向下兼容无影响。

$mask：是否设置掩码【v4.4.12 已移除此参数】

返回值：返回打包好的 WebSocket 数据包，可通过 Swoole\Server 基类的 send() 发送给对端

$ws = new Swoole\Server('127.0.0.1', 9501 , SWOOLE_BASE);

$ws->set(array(
    'log_file' => '/dev/null'
));

$ws->on('WorkerStart', function (\Swoole\Server $serv) {
});

$ws->on('receive', function ($serv, $fd, $threadId, $data) {
    $sendData = "HTTP/1.1 101 Switching Protocols\r\n";
    $sendData .= "Upgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: IFpdKwYy9wdo4gTldFLHFh3xQE0=\r\n";
    $sendData .= "Sec-WebSocket-Version: 13\r\nServer: swoole-http-server\r\n\r\n";
    $sendData .= Swoole\WebSocket\Server::pack("hello world\n");
    $serv->send($fd, $sendData);
});

$ws->start();

unpack：解析 WebSocket 数据帧。

Swoole\WebSocket\Server::unpack(string $data): Swoole\WebSocket\Frame|false;

$data：消息内容

返回值：解析失败返回 false，解析成功返回 Swoole\WebSocket\Frame 对象

disconnect：主动向 WebSocket 客户端发送关闭帧并关闭该连接。

Swoole\WebSocket\Server->disconnect(int $fd, int $code = SWOOLE_WEBSOCKET_CLOSE_NORMAL, string $reason = ''): bool

$fd：客户端连接的 ID【如果指定的 $fd 对应的 TCP 连接并非 WebSocket 客户端，将会发送失败】

$code：关闭连接的状态码【根据 RFC6455，对于应用程序关闭连接状态码，取值范围为 1000 或 4000-4999 之间】

$reason：关闭连接的原因【utf-8 格式字符串，字节长度不超过 125】

返回值：发送成功返回 true，发送失败或状态码非法时返回 false

注意：Swoole 版本 >= v4.0.3 可用

isEstablished：检查连接是否为有效的 WebSocket 客户端连接。此函数与 exist 方法不同，exist 方法仅判断是否为 TCP 连接，无法判断是否为已完成握手的 WebSocket 客户端。

Swoole\WebSocket\Server->isEstablished(int $fd): bool

$fd：客户端连接的 ID【如果指定的 $fd 对应的 TCP 连接并非 WebSocket 客户端，将会发送失败】

2、配置选项

WebSocket\Server 是 Server 的子类，可以使用 Server->set() 方法传入配置选项，设置配置选项参数。

· websocket_subprotocol：设置 WebSocket 子协议。设置后握手响应的 HTTP 头会增加 Sec-WebSocket-Protocol: {$websocket_subprotocol}。

示例代码：

$server->set([
    'websocket_subprotocol' => 'chat',
]);

· open_websocket_close_frame：启用 WebSocket 协议中关闭帧（opcode 为 0x08 的帧）在 onMessage 回调中接收，默认为 false。开启后，可在 Swoole\WebSocket\Server 中的 onMessage 回调中接收到客户端或服务端发送的关闭帧，开发者可自行对其进行处理。

示例代码：

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
$server->set(array("open_websocket_close_frame" => true));
$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
});

$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    if ($frame->opcode == 0x08) {
        echo "Close frame received: Code {$frame->code} Reason {$frame->reason}\n";
    } else {
        echo "Message received: {$frame->data}\n";
    }
});

$server->on('close', function ($ser, $fd) {
});

$server->start();

· open_websocket_ping_frame：启用 WebSocket 协议中 Ping 帧（opcode 为 0x09 的帧）在 onMessage 回调中接收，默认为 false。开启后，可在 Swoole\WebSocket\Server 中的 onMessage 回调中接收到客户端或服务端发送的 Ping 帧，开发者可自行对其进行处理。值为 false 时底层会自动回复 Pong 帧，但如果设为 true 后则需要开发者自行回复 Pong 帧。Swoole 版本 >= v4.5.4 可用。

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
$server->set(array("open_websocket_ping_frame" => true));
$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
});

$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    if ($frame->opcode == 0x09) {
        echo "Ping frame received: Code {$frame->opcode}\n";
        // 回复 Pong 帧
        $pongFrame = new Swoole\WebSocket\Frame;
        $pongFrame->opcode = WEBSOCKET_OPCODE_PONG;
        $server->push($frame->fd, $pongFrame);
    } else {
        echo "Message received: {$frame->data}\n";
    }
});

$server->on('close', function ($ser, $fd) {
});

$server->start();

· open_websocket_pong_frame：启用 WebSocket 协议中 Pong 帧（opcode 为 0x0A 的帧）在 onMessage 回调中接收，默认为 false。开启后，可在 Swoole\WebSocket\Server 中的 onMessage 回调中接收到客户端或服务端发送的 Pong 帧，开发者可自行对其进行处理。Swoole 版本 >= v4.5.4 可用

示例代码：

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
$server->set(array("open_websocket_pong_frame" => true));
$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
});

$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    if ($frame->opcode == 0xa) {
        echo "Pong frame received: Code {$frame->opcode}\n";
    } else {
        echo "Message received: {$frame->data}\n";
    }
});

$server->on('close', function ($ser, $fd) {
});

$server->start();

· websocket_compression：启用数据压缩。为 true 时允许对帧进行 zlib 压缩，具体是否能够压缩取决于客户端是否能够处理压缩（根据握手信息决定，参见 RFC-7692） 需要配合 flags 参数 SWOOLE_WEBSOCKET_FLAG_COMPRESS 来真正地对具体的某个帧进行压缩。Swoole 版本 >= v4.4.12 可用

use Swoole\WebSocket\Frame;
use Swoole\WebSocket\Server;

$server = new Server('127.0.0.1', 9501);
$server->set(['websocket_compression' => true]);
$server->on('message', function (Server $server, Frame $frame) {
    $server->push(
        $frame->fd,
        'Hello Swoole',
        SWOOLE_WEBSOCKET_OPCODE_TEXT,
        SWOOLE_WEBSOCKET_FLAG_FIN | SWOOLE_WEBSOCKET_FLAG_COMPRESS
    );
    // $server->push($frame->fd, $frame); // 或者 服务端可以直接原封不动转发客户端的帧对象
});
$server->start();

 下一篇：Swoole从入门到入土(18)——WebSocket服务器[心跳ping]