物件WebSocketMessage

WebSocketMessage是WebSocket協定中的一種訊息類型，它封裝了WebSocket傳輸協定中各類訊息的資料格式及處理方式，可用於WebSocket客戶端和服務端雙方通訊。

類別的建構子WebSocketMessage支援指定的訊息類型參數type，此參數有三個可選值：

• ws.TEXT：代表文字類型的消息，內容為字串。
• ws.BINARY：代表二進位類型的消息，內容為二進位資料。

另外，還可以透過修改WebSocketMessage.masked屬性指定是否需要套用掩碼，透過WebSocketMessage.compress屬性指定是否需要壓縮。

以下程式碼是一個websocket 伺服器的範例，當有客戶端連線進來之後，伺服器會把收到的訊息echo 回去給客戶端：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var ws = require('ws');
var http = require('http');

var svr = new http.Server(8080, {
    '/websocket': ws.upgrade((conn, req) => {
        // emit message event
        conn.onmessage = e => {
            if (e.data.type == ws.TEXT) {
                console.log(`接收到客户端发来的消息 ${e.data}`);
                conn.send(e.data);
            } else {
                console.error(`收到未知类型消息 ${e.data.type}`);
            }
        }
        conn.onclose = e => console.log('离开了一个客户端');
    })
});
svr.start();

在這個程式中，首先載入了websocket 支援模組和內建的http模組，然後創建了http服務對象，並指定了要處理的請求路徑，呼叫了ws.upgrade函數將對應路徑的請求升級成websocket 連線。建立websocket 連線之後，伺服器會自動為每個連線建立一個ws.Socket對象，並提供了onopen、onmessage、onclose 等API，用來處理當有客戶端連線、收到訊息以及關閉事件。在收到訊息時，伺服器會判斷訊息的類型，如果是文字類型，就會將收到的訊息echo 回去。以上是一個簡單的websocket 伺服器的處理流程，適當地根據實際需求進行修改即可。

繼承關係

建構函數

WebSocketMessage

包處理訊息物件建構函數

1
2
3
4
new WebSocketMessage(Integer type = ws.BINARY,
    Boolean masked = true,
    Boolean compress = false,
    Integer maxSize = 67108864);

呼叫參數:

• type: Integer, websocket 訊息類型，缺省為websocket.BINARY
• masked: Boolean, websocket 訊息掩碼，預設為true
• compress: Boolean, 標記訊息是否壓縮，缺省為false
• maxSize: Integer, 最大包尺寸，以MB 為單位，預設為67108864(64M)

常量

TEXT

指定訊息類型1，代表一個文字類型

1
const WebSocketMessage.TEXT = 1;

---

BINARY

指定訊息類型2，代表一個二進位類型

1
const WebSocketMessage.BINARY = 2;

成員屬性

masked

Boolean, 查詢並讀取websocket 遮罩標記，預設為true

1
Boolean WebSocketMessage.masked;

---

compress

Boolean, 查詢並讀取websocket 壓縮狀態，缺省為false

1
Boolean WebSocketMessage.compress;

---

maxSize

Integer, 查詢並設定最大包尺寸，以位元組為單位，缺省為67108864(64M)

1
Integer WebSocketMessage.maxSize;

---

value

String, 訊息的基本內容

1
String WebSocketMessage.value;

---

params

NArray, 訊息的基本參數

1
readonly NArray WebSocketMessage.params;

---

type

Integer, 訊息類型

1
Integer WebSocketMessage.type;

---

data

Value, 查詢訊息的數據，此屬性會根據content-type 傳回不同數據，當text 時，傳回文本，為json時返回json，其它時候返回二進制

1
readonly Value WebSocketMessage.data;

---

body

SeekableStream, 包含訊息資料部分的流對象

1
SeekableStream WebSocketMessage.body;

---

length

Long, 訊息資料部分的長度

1
readonly Long WebSocketMessage.length;

---

stream

Stream, 查詢訊息readFrom 時的流對象

1
readonly Stream WebSocketMessage.stream;

---

lastError

String, 查詢與設定訊息處理的最後錯誤

1
String WebSocketMessage.lastError;

成員函數

read

從流內讀取指定大小的數據，此方法為body 對應方法的別名

1
Buffer WebSocketMessage.read(Integer bytes = -1) async;

呼叫參數:

• bytes: Integer, 指定要讀取的資料量，預設為讀取隨機大小的資料區塊，讀取的資料尺寸取決於設備

回傳結果:

• Buffer, 傳回從流內讀取的數據，若無數據可讀，或連線中斷，則傳回null

---

readAll

從流內讀取剩餘的全部數據，此方法為body 對應方法的別名

1
Buffer WebSocketMessage.readAll() async;

回傳結果:

• Buffer, 傳回從流內讀取的數據，若無數據可讀，或連線中斷，則傳回null

---

write

寫入給定的數據，此方法為body 對應方法的別名

1
WebSocketMessage.write(Buffer data) async;

呼叫參數:

• data:Buffer, 給定要寫入的數據

---

json

以JSON 編碼寫入給定的數據

1
Value WebSocketMessage.json(Value data);

呼叫參數:

• data: Value, 給定要寫入的數據

回傳結果:

• Value, 此方法不會傳回數據

---

以JSON 編碼解析訊息中的數據

1
Value WebSocketMessage.json();

回傳結果:

• Value, 回傳解析的結果

---

pack

以msgpack編碼寫入給定的數據

1
Value WebSocketMessage.pack(Value data);

呼叫參數:

• data: Value, 給定要寫入的數據

回傳結果:

• Value, 此方法不會傳回數據

---

以msgpack編碼解析訊息中的數據

1
Value WebSocketMessage.pack();

回傳結果:

• Value, 回傳解析的結果

---

end

設定當前訊息處理結束，Chain處理器不再繼續後面的事務

1
WebSocketMessage.end();

---

isEnded

查詢目前訊息是否結束

1
Boolean WebSocketMessage.isEnded();

回傳結果:

• Boolean, 結束則回傳true

---

clear

清除訊息的內容

1
WebSocketMessage.clear();

---

sendTo

發送格式化訊息到給定的流對象

1
WebSocketMessage.sendTo(Stream stm) async;

呼叫參數:

• stm:Stream, 指定接收格式化訊息的流對象

---

readFrom

從給定的快取流對象讀取格式化訊息，並解析填充對象

1
WebSocketMessage.readFrom(Stream stm) async;

呼叫參數:

• stm:Stream, 指定讀取格式化訊息的流對象

---

toString

傳回物件的字串表示，一般回傳"[Native Object]"，物件可以根據自己的特性重新實現

1
String WebSocketMessage.toString();

回傳結果:

• String, 傳回物件的字串表示

---

toJSON

傳回物件的JSON 格式表示，一般傳回物件定義的可讀屬性集合

1
Value WebSocketMessage.toJSON(String key = "");

呼叫參數:

• key: String, 未使用

回傳結果:

• Value, 傳回包含可JSON 序列化的值