Subversion Repositories qbpwcf-lib(archive)

Rev

Rev 915 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
1 liveuser 1 
WebSocketRequest
2 
================
3 
 
4 
* [Constructor](#constructor)
5 
* [Properties](#properties)
6 
* [Methods](#methods)
7 
* [Events](#events)
8 
 
9 
This object represents a client requesting to connect to the server, and allows you to accept or reject the connection based on whatever criteria you decide.
10 
 
11 
Constructor
12 
-----------
13 
This object is created internally by `WebSocketServer`.
14 
 
15 
However if you need to integrate WebSocket support without mounting an instance of `WebSocketServer` to your http server directly, you can handle the `upgrade` event yourself and pass the appropriate parameters to the `WebSocketRequest` constructor.  **NOTE:** You *must* pass a complete set of config options to the constructor.  See the section *'Server Config Options'* above.  The only option that isn't required in this context is `httpServer`.
16 
 
17 
```javascript
18 
new WebSocketRequest(socket, httpRequest, config);
19 
```
20 
 
21 
The constructor won't immediately parse and validate the handshake from the client, so you need to call `readHandshake()`, which will `throw` an error if the handshake from the client is invalid or if an error is encountered, so it must always be wrapped in a try/catch block.
22 
 
23 
Properties
24 
----------
25 
###httpRequest
26 
 
27 
A reference to the original Node HTTP request object.  This may be useful in combination with some other Node-based web server, such as Express, for accessing cookies or session data.
28 
 
29 
 
30 
###host
31 
 
32 
A string containing the contents of the `Host` header passed by the client.  This will include the port number if a non-standard port is used.
33 
 
34 
Examples:
35 
```
36 
www.example.com
37 
www.example.com:8080
38 
127.0.0.1:3000
39 
```
40 
 
41 
###resource
42 
 
43 
A string containing the path that was requested by the client.
44 
 
45 
###resourceURL
46 
 
47 
A Node URL object containing the parsed `resource`, including the query string parameters.
48 
 
49 
###remoteAddress
50 
 
51 
The remote client's IP Address as a string.  If an `X-Forwarded-For` header is present, the value will be taken from that header to facilitate WebSocket servers that live behind a reverse-proxy.
52 
 
53 
###websocketVersion
54 
 
55 
**Deprecated, renamed to webSocketVersion**
56 
 
57 
###webSocketVersion
58 
 
59 
A number indicating the version of the WebSocket protocol requested by the client.
60 
 
61 
###origin
62 
 
63 
If the client is a web browser, `origin` will be a string containing the URL of the page containing the script that opened the connection.  If the client is **not** a web browser, `origin` may be `null` or "*".
64 
 
65 
###requestedExtensions
66 
 
67 
An array containing a list of extensions requested by the client.  This is not currently used for anything. **Example:**
68 
 
69 
```javascript
70 
[
71 
    {
72 
        name: "simple-extension";
73 
    },
74 
    {
75 
        name: "my-great-compression-extension",
76 
        params: [
77 
            {
78 
                name: "compressionLevel",
79 
                value: "10";
80 
            }
81 
        ]
82 
    }
83 
]
84 
```
85 
 
86 
###requestedProtocols
87 
 
88 
An array containing a list of strings that indicate the subprotocols the client would like to speak.  The server should select the best one that it can support from the list and pass it to the accept() function when accepting the connection.  Note that all the strings in the `requestedProtocols` array will have been converted to lower case, so that acceptance of a subprotocol can be case-insensitive.
89 
 
90 
Methods
91 
-------
92 
 
93 
###accept(acceptedProtocol, allowedOrigin)
94 
*Returns: WebSocketConnection instance*
95 
 
96 
After inspecting the WebSocketRequest's properties, call this function on the request object to accept the connection.  If you don't have a particular subprotocol you wish to speak, you may pass `null` for the `acceptedProtocol` parameter.  Note that the `acceptedProtocol` parameter is *case-insensitive*, and you must either pass a value that was originally requested by the client or `null`.  For browser clients (in which the `origin` property would be non-null) you must pass that user's origin as the `allowedOrigin` parameter to confirm that you wish to accept connections from the given origin.  The return value contains the established `WebSocketConnection` instance that can be used to communicate with the connected client.
97 
 
98 
###reject([httpStatus], [reason])
99 
 
100 
If you decide to reject the connection, you must call `reject`.  You may optionally pass in an HTTP Status code (such as 404) and a textual description that will be sent to the client in the form of an "X-WebSocket-Reject-Reason" header.  The connection will then be closed.
101 
 
102 
Events
103 
------
104 
 
105 
###requestAccepted
106 
`function(webSocketConnection)`
107 
 
108 
Emitted by the WebSocketRequest object when the `accept` method has been called and the connection has been established.  `webSocketConnection` is the established `WebSocketConnection` instance that can be used to communicate with the connected client.
109 
 
110 
###requestRejected
111 
`function()`
112 
 
113 
Emitted by the WebSocketRequest object when the `reject` method has been called and the connection has been terminated.