comunicationLeap/node_modules/engine.io-client/README.md
node_modules/engine.io-client/README.mdRaw
1
2# Engine.IO client
3
4[](http://travis-ci.org/Automattic/engine.io-client)
5[](http://badge.fury.io/js/engine.io-client)
6
7This is the client for [Engine.IO](http://github.com/automattic/engine.io),
8the implementation of transport-based cross-browser/cross-device
9bi-directional communication layer for [Socket.IO](http://github.com/automattic/socket.io).
10
11## How to use
12
13### Standalone
14
15You can find an `engine.io.js` file in this repository, which is a
16standalone build you can use as follows:
17
18```html
19<script src="/path/to/engine.io.js"></script>
20<script>
21 // eio = Socket
22 var socket = eio('ws://localhost');
23 socket.on('open', function(){
24 socket.on('message', function(data){});
25 socket.on('close', function(){});
26 });
27</script>
28```
29
30### With browserify
31
32Engine.IO is a commonjs module, which means you can include it by using
33`require` on the browser and package using [browserify](http://browserify.org/):
34
351. install the client package
36
37 ```bash
38 $ npm install engine.io-client
39 ```
40
411. write your app code
42
43 ```js
44 var socket = require('engine.io-client')('ws://localhost');
45 socket.on('open', function(){
46 socket.on('message', function(data){});
47 socket.on('close', function(){});
48 });
49 ```
50
511. build your app bundle
52
53 ```bash
54 $ browserify app.js > bundle.js
55 ```
56
571. include on your page
58
59 ```html
60 <script src="/path/to/bundle.js"></script>
61 ```
62
63### Sending and receiving binary
64
65```html
66<script src="/path/to/engine.io.js"></script>
67<script>
68 var socket = new eio.Socket('ws://localhost/');
69 socket.binaryType = 'blob';
70 socket.on('open', function () {
71 socket.send(new Int8Array(5));
72 socket.on('message', function(blob){});
73 socket.on('close', function(){ });
74 });
75</script>
76```
77
78### Node.JS
79
80Add `engine.io-client` to your `package.json` and then:
81
82```js
83var socket = require('engine.io-client')('ws://localhost');
84socket.on('open', function(){
85 socket.on('message', function(data){});
86 socket.on('close', function(){});
87});
88```
89
90## Features
91
92- Lightweight
93- Runs on browser and node.js seamlessly
94- Transports are independent of `Engine`
95 - Easy to debug
96 - Easy to unit test
97- Runs inside HTML5 WebWorker
98- Can send and receive binary data
99 - Receives as ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer
100 in Node
101 - When XHR2 or WebSockets are used, binary is emitted directly. Otherwise
102 binary is encoded into base64 strings, and decoded when binary types are
103 supported.
104 - With browsers that don't support ArrayBuffer, an object { base64: true,
105 data: dataAsBase64String } is emitted on the `message` event.
106
107## API
108
109### Socket
110
111The client class. Mixes in [Emitter](http://github.com/component/emitter).
112Exposed as `eio` in the browser standalone build.
113
114#### Properties
115
116- `protocol` _(Number)_: protocol revision number
117- `binaryType` _(String)_ : can be set to 'arraybuffer' or 'blob' in browsers,
118 and `buffer` or `arraybuffer` in Node. Blob is only used in browser if it's
119 supported.
120
121#### Events
122
123- `open`
124 - Fired upon successful connection.
125- `message`
126 - Fired when data is received from the server.
127 - **Arguments**
128 - `String` | `ArrayBuffer`: utf-8 encoded data or ArrayBuffer containing
129 binary data
130- `close`
131 - Fired upon disconnection. In compliance with the WebSocket API spec, this event may be
132 fired even if the `open` event does not occur (i.e. due to connection error or `close()`).
133- `error`
134 - Fired when an error occurs.
135- `flush`
136 - Fired upon completing a buffer flush
137- `drain`
138 - Fired after `drain` event of transport if writeBuffer is empty
139- `upgradeError`
140 - Fired if an error occurs with a transport we're trying to upgrade to.
141- `upgrade`
142 - Fired upon upgrade success, after the new transport is set
143
144#### Methods
145
146- **constructor**
147 - Initializes the client
148 - **Parameters**
149 - `String` uri
150 - `Object`: optional, options object
151 - **Options**
152 - `agent` (`http.Agent`): `http.Agent` to use, defaults to `false` (NodeJS only)
153 - `upgrade` (`Boolean`): defaults to true, whether the client should try
154 to upgrade the transport from long-polling to something better.
155 - `forceJSONP` (`Boolean`): forces JSONP for polling transport.
156 - `jsonp` (`Boolean`): determines whether to use JSONP when
157 necessary for polling. If disabled (by settings to false) an error will
158 be emitted (saying "No transports available") if no other transports
159 are available. If another transport is available for opening a
160 connection (e.g. WebSocket) that transport
161 will be used instead.
162 - `forceBase64` (`Boolean`): forces base 64 encoding for polling transport even when XHR2 responseType is available and WebSocket even if the used standard supports binary.
163 - `enablesXDR` (`Boolean`): enables XDomainRequest for IE8 to avoid loading bar flashing with click sound. default to `false` because XDomainRequest has a flaw of not sending cookie.
164 - `timestampRequests` (`Boolean`): whether to add the timestamp with
165 each transport request. Note: this is ignored if the browser is
166 IE or Android, in which case requests are always stamped (`false`)
167 - `timestampParam` (`String`): timestamp parameter (`t`)
168 - `policyPort` (`Number`): port the policy server listens on (`843`)
169 - `path` (`String`): path to connect to, default is `/engine.io`
170 - `transports` (`Array`): a list of transports to try (in order).
171 Defaults to `['polling', 'websocket']`. `Engine`
172 always attempts to connect directly with the first one, provided the
173 feature detection test for it passes.
174 - `rememberUpgrade` (`Boolean`): defaults to false.
175 If true and if the previous websocket connection to the server succeeded,
176 the connection attempt will bypass the normal upgrade process and will initially
177 try websocket. A connection attempt following a transport error will use the
178 normal upgrade process. It is recommended you turn this on only when using
179 SSL/TLS connections, or if you know that your network does not block websockets.
180- `send`
181 - Sends a message to the server
182 - **Parameters**
183 - `String` | `ArrayBuffer` | `ArrayBufferView` | `Blob`: data to send
184 - `Function`: optional, callback upon `drain`
185- `close`
186 - Disconnects the client.
187
188### Transport
189
190The transport class. Private. _Inherits from EventEmitter_.
191
192#### Events
193
194- `poll`: emitted by polling transports upon starting a new request
195- `pollComplete`: emitted by polling transports upon completing a request
196- `drain`: emitted by polling transports upon a buffer drain
197
198## Tests
199
200`engine.io-client` is used to test
201[engine](http://github.com/automattic/engine.io). Running the `engine.io`
202test suite ensures the client works and vice-versa.
203
204Browser tests are run using [zuul](https://github.com/defunctzombie/zuul). You can
205run the tests locally using the following command.
206
207```
208./node_modules/.bin/zuul --local 8080 -- test/index.js
209```
210
211Additionally, `engine.io-client` has a standalone test suite you can run
212with `make test` which will run node.js and browser tests. You must have zuul setup with
213a saucelabs account.
214
215## Support
216
217The support channels for `engine.io-client` are the same as `socket.io`:
218 - irc.freenode.net **#socket.io**
219 - [Google Groups](http://groups.google.com/group/socket_io)
220 - [Website](http://socket.io)
221
222## Development
223
224To contribute patches, run tests or benchmarks, make sure to clone the
225repository:
226
227```bash
228git clone git://github.com/automattic/engine.io-client.git
229```
230
231Then:
232
233```bash
234cd engine.io-client
235npm install
236```
237
238See the `Tests` section above for how to run tests before submitting any patches.
239
240## License
241
242MIT - Copyright (c) 2014 Automattic, Inc.
243