1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
WebSocketConnection
===================
* [Constructor](#constructor)
* [Properties](#properties)
* [Methods](#methods)
* [Events](#events)
This object provides the interface through which you can communicate with connected peers. It is used in both WebSocketServer and WebSocketClient situations.
Constructor
-----------
This object is created internally by `WebSocketRequest`.
Properties
----------
### closeDescription
After the connection is closed, contains a textual description of the reason for the connection closure, or `null` if the connection is still open.
### closeReasonCode
After the connection is closed, contains the numeric close reason status code, or `-1` if the connection is still open.
### socket
The underlying net.Socket instance for the connection.
### protocol
The subprotocol that was chosen to be spoken on this connection. This field will have been converted to lower case.
### extensions
An array of extensions that were negotiated for this connection. Currently unused, will always be an empty array.
### remoteAddress
The IP address of the remote peer as a string. In the case of a server, the `X-Forwarded-For` header will be respected and preferred for the purposes of populating this field. If you need to get to the actual remote IP address, `webSocketConnection.socket.remoteAddress` will provide it.
### webSocketVersion
A number indicating the version of the WebSocket protocol being spoken on this connection.
### connected
A boolean value indicating whether or not the connection is still connected. *Read-only*
Methods
-------
### close([reasonCode], [description])
Will gracefully close the connection. A close frame will be sent to the remote peer with the provided `reasonCode` and `description` indicating that we wish to close the connection, and we will then wait for up to `config.closeTimeout` milliseconds for an acknowledgment from the remote peer before terminating the underlying socket connection. The `closeTimeout` is passed as part of the `serverOptions` or `clientOptions` hashes to either the `WebSocketServer` or `WebSocketClient` constructors. Most of the time, you should call `close()` without arguments to initiate a normal connection closure. If you specify a `reasonCode` that is defined as one of the standard codes in the WebSocket protocol specification and do not provide a `description`, the default description for the given code will be used. If you would prefer not to send a description at all, pass an empty string `''`as the description parameter.
### drop([reasonCode], [description])
Will send a close frame to the remote peer with the provided `reasonCode` and `description` and will immediately close the socket without waiting for a response. This should generally be used only in error conditions. The default `reasonCode` is 1002 (Protocol Error). Close reasons defined by the WebSocket protocol draft include:
```javascript
WebSocketConnection.CLOSE_REASON_NORMAL = 1000;
WebSocketConnection.CLOSE_REASON_GOING_AWAY = 1001;
WebSocketConnection.CLOSE_REASON_PROTOCOL_ERROR = 1002;
WebSocketConnection.CLOSE_REASON_UNPROCESSABLE_INPUT = 1003;
WebSocketConnection.CLOSE_REASON_RESERVED = 1004; // Reserved value. Undefined meaning.
WebSocketConnection.CLOSE_REASON_NOT_PROVIDED = 1005; // Not to be used on the wire
WebSocketConnection.CLOSE_REASON_ABNORMAL = 1006; // Not to be used on the wire
WebSocketConnection.CLOSE_REASON_INVALID_DATA = 1007;
WebSocketConnection.CLOSE_REASON_POLICY_VIOLATION = 1008;
WebSocketConnection.CLOSE_REASON_MESSAGE_TOO_BIG = 1009;
WebSocketConnection.CLOSE_REASON_EXTENSION_REQUIRED = 1010;
```
### sendUTF(string)
Immediately sends the specified string as a UTF-8 WebSocket message to the remote peer. If `config.fragmentOutgoingMessages` is `true` the message may be sent as multiple fragments if it exceeds `config.fragmentationThreshold` bytes. Any object that implements the `toString()` method may be passed to `sendUTF()`
### sendBytes(buffer)
Immediately sends the specified Node `Buffer` object as a Binary WebSocket message to the remote peer. If `config.fragmentOutgoingMessages` is `true` the message may be sent as multiple fragments if it exceeds `config.fragmentationThreshold` bytes.
### send(data)
A convenience function that will auto-detect the data type and send the appropriate WebSocket message accordingly. Immediately sends the specified data as either a UTF-8 or Binary message. If `data` is a Node Buffer, a binary message will be sent. Otherwise, the object provided must implement the `toString()` method, and the result of calling `toString()` on the `data` object will be sent as a UTF-8 message.
### ping(data)
Sends a ping frame to the remote peer. `data` can be a Node `Buffer` or any object that implements `toString()`, such as a `string` or `number`. Ping frames must not exceed 125 bytes in length.
### pong(buffer)
Sends a pong frame to the remote peer. Pong frames may be sent unsolicited and such pong frames will trigger no action on the receiving peer. Pong frames sent in response to a ping frame must mirror the payload data of the ping frame exactly. The `WebSocketConnection` object handles this internally for you, so there should be no need to use this method to respond to pings unless you explicitly cancel() this internal behavior (see ping event below). Pong frames must not exceed 125 bytes in length.
### sendFrame(webSocketFrame)
Serializes a `WebSocketFrame` object into binary data and immediately sends it to the remote peer. This is an advanced function, requiring you to manually compose your own `WebSocketFrame`. You should probably use `sendUTF` or `sendBytes` instead.
Events
------
### message
`function(message)`
Emitted whenever a complete single-frame message is received, or if `config.assembleFragments` is `true` (the default), it will also be emitted with a complete message assembled from multiple fragmented frames. This is the primary event to listen for to receive messages from the remote peer. The `message` object looks like the following:
```javascript
// For Text Frames:
{
type: "utf8",
utf8Data: "A string containing the received message."
}
// For Binary Frames:
{
type: "binary",
binaryData: binaryDataBuffer // a Buffer object containing the binary message payload
}
```
### frame
`function(webSocketFrame)`
This event is emitted only if `config.assembleFragments` is `false` (default is `true`). This allows you to handle individual fragments as they are received without waiting on `WebSocketConnection` to buffer them into a single `message` event for you. This may be desirable if you are working with streaming data, as it is possible to send fragments continually without ever stopping. `webSocketFrame` is an instance of `WebSocketFrame` which has properties that represent all the individual fields in WebSocket's binary framing protocol.
### close
`function(reasonCode, description)`
This event is emitted when the connection has been fully closed and the socket is no longer connected. `reasonCode` is the numeric reason code for the connection closure. `description` is a textual explanation for the connection closure, if available.
### error
`function(error)`
This event is emitted when there has been a socket error. If this occurs, a `close` event will also be emitted.
### ping
`function(cancel, data)`
This event is emitted when the connection receives a `ping` from the peer. `cancel` is a function taking no arguments that when called prevents the WebSocketConnection object from automatically replying with a `pong`. `data` is the binary payload contained in the ping frame.
### pong
`function(data)`
This event is emitted when the connection receives a `pong` from the peer. `data` is the binary data contained in the pong frame.
|
