OLD | NEW |
| (Empty) |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 /** | |
6 * Web socket status codes used when closing a web socket connection. | |
7 */ | |
8 abstract class WebSocketStatus { | |
9 static const int NORMAL_CLOSURE = 1000; | |
10 static const int GOING_AWAY = 1001; | |
11 static const int PROTOCOL_ERROR = 1002; | |
12 static const int UNSUPPORTED_DATA = 1003; | |
13 static const int RESERVED_1004 = 1004; | |
14 static const int NO_STATUS_RECEIVED = 1005; | |
15 static const int ABNORMAL_CLOSURE = 1006; | |
16 static const int INVALID_FRAME_PAYLOAD_DATA = 1007; | |
17 static const int POLICY_VIOLATION = 1008; | |
18 static const int MESSAGE_TOO_BIG = 1009; | |
19 static const int MISSING_MANDATORY_EXTENSION = 1010; | |
20 static const int INTERNAL_SERVER_ERROR = 1011; | |
21 static const int RESERVED_1015 = 1015; | |
22 } | |
23 | |
24 /** | |
25 * The web socket protocol is implemented by a HTTP server handler | |
26 * which can be instantiated like this: | |
27 * | |
28 * WebSocketHandler wsHandler = new WebSocketHandler(); | |
29 * | |
30 * and then its onRequest method can be assigned to the HTTP server, e.g. | |
31 * | |
32 * server.defaultHandler = wsHandler.onRequest; | |
33 * | |
34 * or | |
35 * | |
36 * server.addRequestHandler((req) => req.path == "/ws", | |
37 * wsHandler.onRequest); | |
38 * | |
39 * This handler strives to implement web sockets as specified by RFC6455. | |
40 */ | |
41 abstract class WebSocketHandler { | |
42 factory WebSocketHandler() => new _WebSocketHandler(); | |
43 | |
44 /** | |
45 * Request handler to be registered with the HTTP server. | |
46 */ | |
47 void onRequest(HttpRequest request, HttpResponse response); | |
48 | |
49 /** | |
50 * Sets the callback to be called when a new web socket connection | |
51 * has been established. | |
52 */ | |
53 void set onOpen(callback(WebSocketConnection connection)); | |
54 } | |
55 | |
56 | |
57 /** | |
58 * Server web socket connection. | |
59 */ | |
60 abstract class WebSocketConnection { | |
61 /** | |
62 * Sets the callback to be called when a message have been | |
63 * received. The type on [message] is either [:String:] or | |
64 * [:List<int>:] depending on whether it is a text or binary | |
65 * message. If the message is empty [message] will be [:null:]. | |
66 */ | |
67 void set onMessage(void callback(message)); | |
68 | |
69 /** | |
70 * Sets the callback to be called when the web socket connection is | |
71 * closed. [status] indicate the reason for closing. For network | |
72 * errors the value of [status] will be | |
73 * WebSocketStatus.ABNORMAL_CLOSURE]. In this callbach it is | |
74 * possible to call [close] if [close] has not already been called. | |
75 * If [close] has still not been called after the close callback | |
76 * returns the received close status will automatically be echoed | |
77 * back to the other end to finish the close handshake. | |
78 */ | |
79 void set onClosed(void callback(int status, String reason)); | |
80 | |
81 /** | |
82 * Sends a message. The [message] must be a [:String:] a | |
83 * [:List<int>:] or [:null:]. | |
84 */ | |
85 send(Object message); | |
86 | |
87 /** | |
88 * Close the web socket connection. The default value for [status] | |
89 * and [reason] are [:null:]. | |
90 */ | |
91 close([int status, String reason]); | |
92 | |
93 /** | |
94 * WebSocketConnection is hashable. | |
95 */ | |
96 int get hashCode; | |
97 } | |
98 | |
99 | |
100 /** | |
101 * Client web socket connection. | |
102 */ | |
103 abstract class WebSocketClientConnection { | |
104 /** | |
105 * Creates a new web socket client connection based on a HTTP client | |
106 * connection. The HTTP client connection must be freshly opened. | |
107 */ | |
108 factory WebSocketClientConnection(HttpClientConnection conn, | |
109 [List<String> protocols]) { | |
110 return new _WebSocketClientConnection(conn, protocols); | |
111 } | |
112 | |
113 /** | |
114 * Sets the callback to be called when the request object for the | |
115 * opening handshake request is ready. This callback can be used if | |
116 * one need to add additional headers to the opening handshake | |
117 * request. | |
118 */ | |
119 void set onRequest(void callback(HttpClientRequest request)); | |
120 | |
121 /** | |
122 * Sets the callback to be called when a web socket connection has | |
123 * been established. | |
124 */ | |
125 void set onOpen(void callback()); | |
126 | |
127 /** | |
128 * Sets the callback to be called when a message have been | |
129 * received. The type of [message] is either [:String:] or | |
130 * [:List<int>:] depending on whether it is a text or binary | |
131 * message. If the message is empty [message] will be [:null:]. | |
132 */ | |
133 void set onMessage(void callback(message)); | |
134 | |
135 /** | |
136 * Sets the callback to be called when the web socket connection is | |
137 * closed. [status] indicate the reason for closing. For network | |
138 * errors the value of [status] will be | |
139 * WebSocketStatus.ABNORMAL_CLOSURE]. | |
140 */ | |
141 void set onClosed(void callback(int status, String reason)); | |
142 | |
143 /** | |
144 * Sets the callback to be called when the response object for the | |
145 * opening handshake did not cause a web socket connection | |
146 * upgrade. This will be called in case the response status code is | |
147 * not 101 (Switching Protocols). If this callback is not set the | |
148 * [:onError:] callback will be called if the server did not upgrade | |
149 * the connection. | |
150 */ | |
151 void set onNoUpgrade(void callback(HttpClientResponse response)); | |
152 | |
153 /** | |
154 * Sends a message. The [message] must be a [:String:] or a | |
155 * [:List<int>:]. To send an empty message use either an empty | |
156 * [:String:] or an empty [:List<int>:]. [:null:] cannot be used. | |
157 */ | |
158 send(message); | |
159 | |
160 /** | |
161 * Close the web socket connection. The default value for [status] | |
162 * and [reason] are [:null:]. | |
163 */ | |
164 close([int status, String reason]); | |
165 | |
166 /** | |
167 * WebSocketClientConnection is hashable. | |
168 */ | |
169 int get hashCode; | |
170 } | |
171 | |
172 | |
173 /** | |
174 * Base class for the events generated by the W3C complient browser | |
175 * API for web sockets. | |
176 */ | |
177 abstract class Event { } | |
178 | |
179 /** | |
180 * Event delivered when there is data on a web socket connection. | |
181 */ | |
182 abstract class MessageEvent extends Event { | |
183 /** | |
184 * The type of [message] is either [:String:] or [:List<int>:] | |
185 * depending on whether it is a text or binary message. If the | |
186 * message is empty [message] will be [:null:] | |
187 */ | |
188 get data; | |
189 } | |
190 | |
191 | |
192 /** | |
193 * Event delivered when a web socket connection is closed. | |
194 */ | |
195 abstract class CloseEvent extends Event { | |
196 /** | |
197 * Returns whether the connection was closed cleanly or not. | |
198 */ | |
199 bool get wasClean; | |
200 | |
201 /** | |
202 * Returns the web socket connection close code provided by the | |
203 * server. | |
204 */ | |
205 int get code; | |
206 | |
207 /** | |
208 * Returns the web socket connection close reason provided by the | |
209 * server. | |
210 */ | |
211 String get reason; | |
212 } | |
213 | |
214 | |
215 /** | |
216 * Alternative web socket client interface. This interface is compliant | |
217 * with the W3C browser API for web sockets specified in | |
218 * http://dev.w3.org/html5/websockets/. | |
219 */ | |
220 abstract class WebSocket { | |
221 /** | |
222 * Possible states of the connection. | |
223 */ | |
224 static const int CONNECTING = 0; | |
225 static const int OPEN = 1; | |
226 static const int CLOSING = 2; | |
227 static const int CLOSED = 3; | |
228 | |
229 /** | |
230 * Create a new web socket connection. The URL supplied in [url] | |
231 * must use the scheme [:ws:]. The [protocols] argument is either a | |
232 * [:String:] or [:List<String>:] specifying the subprotocols the | |
233 * client is willing to speak. | |
234 */ | |
235 factory WebSocket(String url, [protocols]) => new _WebSocket(url, protocols); | |
236 | |
237 /** | |
238 * Returns the current state of the connection. | |
239 */ | |
240 int get readyState; | |
241 | |
242 /** | |
243 * Returns the number of bytes currently buffered for transmission. | |
244 */ | |
245 int get bufferedAmount; | |
246 | |
247 /** | |
248 * Sets the callback to be called when a web socket connection has | |
249 * been established. | |
250 */ | |
251 void set onopen(void callback()); | |
252 | |
253 /** | |
254 * Sets the callback to be called when the web socket connection | |
255 * encountered an error. | |
256 */ | |
257 void set onerror(void callback(e)); | |
258 | |
259 /** | |
260 * Sets the callback to be called when the web socket connection is | |
261 * closed. | |
262 */ | |
263 void set onclose(void callback(CloseEvent event)); | |
264 | |
265 /** | |
266 * The extensions property is initially the empty string. After the | |
267 * web socket connection is established this string reflects the | |
268 * extensions used by the server. | |
269 */ | |
270 String get extensions; | |
271 | |
272 /** | |
273 * The protocol property is initially the empty string. After the | |
274 * web socket connection is established the value is the subprotocol | |
275 * selected by the server. If no subprotocol is negotiated the | |
276 * value will remain [:null:]. | |
277 */ | |
278 String get protocol; | |
279 | |
280 /** | |
281 * Closes the web socket connection. | |
282 */ | |
283 void close(int code, String reason); | |
284 | |
285 /** | |
286 * Sets the callback to be called when a message have been | |
287 * received. | |
288 */ | |
289 void set onmessage(void callback(MessageEvent event)); | |
290 | |
291 /** | |
292 * Sends data on the web socket connection. The data in [data] must | |
293 * be either a [:String:] or [:List<int>:] holding bytes. | |
294 */ | |
295 void send(data); | |
296 } | |
297 | |
298 | |
299 class WebSocketException implements Exception { | |
300 const WebSocketException([String this.message = ""]); | |
301 String toString() => "WebSocketException: $message"; | |
302 final String message; | |
303 } | |
OLD | NEW |