example/iot-gateway/node_modules/engine.io-client/README.md

   1
   2 # Engine.IO client
   3
   4 [![Build Status](https://secure.travis-ci.org/socketio/engine.io-client.svg)](http://travis-ci.org/socketio/engine.io-client)
   5 [![NPM version](https://badge.fury.io/js/engine.io-client.svg)](http://badge.fury.io/js/engine.io-client)
   6
   7 This is the client for [Engine.IO](http://github.com/socketio/engine.io),
   8 the implementation of transport-based cross-browser/cross-device
   9 bi-directional communication layer for [Socket.IO](http://github.com/socketio/socket.io).
  10
  11 ## How to use
  12
  13 ### Standalone
  14
  15 You can find an `engine.io.js` file in this repository, which is a
  16 standalone 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
  32 Engine.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
  35 1. install the client package
  36
  37     ```bash
  38     $ npm install engine.io-client
  39     ```
  40
  41 1. 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
  51 1. build your app bundle
  52
  53     ```bash
  54     $ browserify app.js > bundle.js
  55     ```
  56
  57 1. 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
  80 Add `engine.io-client` to your `package.json` and then:
  81
  82 ```js
  83 var socket = require('engine.io-client')('ws://localhost');
  84 socket.on('open', function(){
  85   socket.on('message', function(data){});
  86   socket.on('close', function(){});
  87 });
  88 ```
  89
  90 ### Node.js with certificates
  91 ```js
  92 var opts = {
  93   key: fs.readFileSync('test/fixtures/client.key'),
  94   cert: fs.readFileSync('test/fixtures/client.crt'),
  95   ca: fs.readFileSync('test/fixtures/ca.crt')
  96 };
  97
  98 var socket = require('engine.io-client')('ws://localhost', opts);
  99 socket.on('open', function(){
 100   socket.on('message', function(data){});
 101   socket.on('close', function(){});
 102 });
 103 ```
 104
 105 ### Node.js with extraHeaders
 106 ```js
 107 var opts = {
 108   extraHeaders: {
 109     'X-Custom-Header-For-My-Project': 'my-secret-access-token',
 110     'Cookie': 'user_session=NI2JlCKF90aE0sJZD9ZzujtdsUqNYSBYxzlTsvdSUe35ZzdtVRGqYFr0kdGxbfc5gUOkR9RGp20GVKza; path=/; expires=Tue, 07-Apr-2015 18:18:08 GMT; secure; HttpOnly'
 111   }
 112 };
 113
 114 var socket = require('engine.io-client')('ws://localhost', opts);
 115 socket.on('open', function(){
 116   socket.on('message', function(data){});
 117   socket.on('close', function(){});
 118 });
 119 ```
 120
 121 ## Features
 122
 123 - Lightweight
 124 - Runs on browser and node.js seamlessly
 125 - Transports are independent of `Engine`
 126   - Easy to debug
 127   - Easy to unit test
 128 - Runs inside HTML5 WebWorker
 129 - Can send and receive binary data
 130   - Receives as ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer
 131     in Node
 132   - When XHR2 or WebSockets are used, binary is emitted directly. Otherwise
 133     binary is encoded into base64 strings, and decoded when binary types are
 134     supported.
 135   - With browsers that don't support ArrayBuffer, an object { base64: true,
 136     data: dataAsBase64String } is emitted on the `message` event.
 137
 138 ## API
 139
 140 ### Socket
 141
 142 The client class. Mixes in [Emitter](http://github.com/component/emitter).
 143 Exposed as `eio` in the browser standalone build.
 144
 145 #### Properties
 146
 147 - `protocol` _(Number)_: protocol revision number
 148 - `binaryType` _(String)_ : can be set to 'arraybuffer' or 'blob' in browsers,
 149   and `buffer` or `arraybuffer` in Node. Blob is only used in browser if it's
 150   supported.
 151
 152 #### Events
 153
 154 - `open`
 155   - Fired upon successful connection.
 156 - `message`
 157   - Fired when data is received from the server.
 158   - **Arguments**
 159     - `String` | `ArrayBuffer`: utf-8 encoded data or ArrayBuffer containing
 160       binary data
 161 - `close`
 162   - Fired upon disconnection. In compliance with the WebSocket API spec, this event may be
 163     fired even if the `open` event does not occur (i.e. due to connection error or `close()`).
 164 - `error`
 165   - Fired when an error occurs.
 166 - `flush`
 167   - Fired upon completing a buffer flush
 168 - `drain`
 169   - Fired after `drain` event of transport if writeBuffer is empty
 170 - `upgradeError`
 171   - Fired if an error occurs with a transport we're trying to upgrade to.
 172 - `upgrade`
 173   - Fired upon upgrade success, after the new transport is set
 174 - `ping`
 175   - Fired upon _flushing_ a ping packet (ie: actual packet write out)
 176 - `pong`
 177   - Fired upon receiving a pong packet.
 178
 179 #### Methods
 180
 181 - **constructor**
 182     - Initializes the client
 183     - **Parameters**
 184       - `String` uri
 185       - `Object`: optional, options object
 186     - **Options**
 187       - `agent` (`http.Agent`): `http.Agent` to use, defaults to `false` (NodeJS only)
 188       - `upgrade` (`Boolean`): defaults to true, whether the client should try
 189       to upgrade the transport from long-polling to something better.
 190       - `forceJSONP` (`Boolean`): forces JSONP for polling transport.
 191       - `jsonp` (`Boolean`): determines whether to use JSONP when
 192         necessary for polling. If disabled (by settings to false) an error will
 193         be emitted (saying "No transports available") if no other transports
 194         are available. If another transport is available for opening a
 195         connection (e.g. WebSocket) that transport
 196         will be used instead.
 197       - `forceBase64` (`Boolean`): forces base 64 encoding for polling transport even when XHR2 responseType is available and WebSocket even if the used standard supports binary.
 198       - `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.
 199       - `timestampRequests` (`Boolean`): whether to add the timestamp with each
 200         transport request. Note: polling requests are always stamped unless this
 201         option is explicitly set to `false` (`false`)
 202       - `timestampParam` (`String`): timestamp parameter (`t`)
 203       - `policyPort` (`Number`): port the policy server listens on (`843`)
 204       - `path` (`String`): path to connect to, default is `/engine.io`
 205       - `transports` (`Array`): a list of transports to try (in order).
 206       Defaults to `['polling', 'websocket']`. `Engine`
 207       always attempts to connect directly with the first one, provided the
 208       feature detection test for it passes.
 209       - `rememberUpgrade` (`Boolean`): defaults to false.
 210         If true and if the previous websocket connection to the server succeeded,
 211         the connection attempt will bypass the normal upgrade process and will initially
 212         try websocket. A connection attempt following a transport error will use the
 213         normal upgrade process. It is recommended you turn this on only when using
 214         SSL/TLS connections, or if you know that your network does not block websockets.
 215       - `pfx` (`String`): Certificate, Private key and CA certificates to use for SSL. Can be used in Node.js client environment to manually specify certificate information.
 216       - `key` (`String`): Private key to use for SSL. Can be used in Node.js client environment to manually specify certificate information.
 217       - `passphrase` (`String`): A string of passphrase for the private key or pfx. Can be used in Node.js client environment to manually specify certificate information.
 218       - `cert` (`String`): Public x509 certificate to use. Can be used in Node.js client environment to manually specify certificate information.
 219       - `ca` (`String`|`Array`): An authority certificate or array of authority certificates to check the remote host against.. Can be used in Node.js client environment to manually specify certificate information.
 220       - `ciphers` (`String`): A string describing the ciphers to use or exclude. Consult the [cipher format list](http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT) for details on the format. Can be used in Node.js client environment to manually specify certificate information.
 221       - `rejectUnauthorized` (`Boolean`): If true, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent. Can be used in Node.js client environment to manually specify certificate information.
 222       - `perMessageDeflate` (`Object|Boolean`): parameters of the WebSocket permessage-deflate extension
 223         (see [ws module](https://github.com/einaros/ws) api docs). Set to `false` to disable. (`true`)
 224         - `threshold` (`Number`): data is compressed only if the byte size is above this value. This option is ignored on the browser. (`1024`)
 225       - `extraHeaders` (`Object`): Headers that will be passed for each request to the server (via xhr-polling and via websockets). These values then can be used during handshake or for special proxies. Can only be used in Node.js client environment.
 226 - `send`
 227     - Sends a message to the server
 228     - **Parameters**
 229       - `String` | `ArrayBuffer` | `ArrayBufferView` | `Blob`: data to send
 230       - `Object`: optional, options object
 231       - `Function`: optional, callback upon `drain`
 232     - **Options**
 233       - `compress` (`Boolean`): whether to compress sending data. This option is ignored and forced to be `true` on the browser. (`true`)
 234 - `close`
 235     - Disconnects the client.
 236
 237 ### Transport
 238
 239 The transport class. Private. _Inherits from EventEmitter_.
 240
 241 #### Events
 242
 243 - `poll`: emitted by polling transports upon starting a new request
 244 - `pollComplete`: emitted by polling transports upon completing a request
 245 - `drain`: emitted by polling transports upon a buffer drain
 246
 247 ## Tests
 248
 249 `engine.io-client` is used to test
 250 [engine](http://github.com/socketio/engine.io). Running the `engine.io`
 251 test suite ensures the client works and vice-versa.
 252
 253 Browser tests are run using [zuul](https://github.com/defunctzombie/zuul). You can
 254 run the tests locally using the following command.
 255
 256 ```
 257 ./node_modules/.bin/zuul --local 8080 -- test/index.js
 258 ```
 259
 260 Additionally, `engine.io-client` has a standalone test suite you can run
 261 with `make test` which will run node.js and browser tests. You must have zuul setup with
 262 a saucelabs account.
 263
 264 ## Support
 265
 266 The support channels for `engine.io-client` are the same as `socket.io`:
 267   - irc.freenode.net **#socket.io**
 268   - [Google Groups](http://groups.google.com/group/socket_io)
 269   - [Website](http://socket.io)
 270
 271 ## Development
 272
 273 To contribute patches, run tests or benchmarks, make sure to clone the
 274 repository:
 275
 276 ```bash
 277 git clone git://github.com/socketio/engine.io-client.git
 278 ```
 279
 280 Then:
 281
 282 ```bash
 283 cd engine.io-client
 284 npm install
 285 ```
 286
 287 See the `Tests` section above for how to run tests before submitting any patches.
 288
 289 ## License
 290
 291 MIT - Copyright (c) 2014 Automattic, Inc.
 292