device_home/node_modules/engine.io-parser/Readme.md

   1
   2 # engine.io-parser
   3
   4 [![Build Status](https://secure.travis-ci.org/socketio/engine.io-parser.svg?branch=master)](https://travis-ci.org/socketio/engine.io-parser)
   5 [![NPM version](https://badge.fury.io/js/engine.io-parser.svg)](https://npmjs.com/package/engine.io-parser)
   6
   7 This is the JavaScript parser for the engine.io protocol encoding,
   8 shared by both
   9 [engine.io-client](https://github.com/socketio/engine.io-client) and
  10 [engine.io](https://github.com/socketio/engine.io).
  11
  12 ## How to use
  13
  14 ### Standalone
  15
  16 The parser can encode/decode packets, payloads, and payloads as binary
  17 with the following methods: `encodePacket`, `decodePacket`, `encodePayload`,
  18 `decodePayload`, `encodePayloadAsBinary`, `decodePayloadAsBinary`.
  19
  20 The browser-side parser also includes `encodePayloadAsArrayBuffer` and `encodePayloadAsBlob`.
  21
  22 Example:
  23
  24 ```js
  25 var parser = require('engine.io-parser');
  26
  27 var data = new Buffer(5);
  28 for (var i = 0; i < data.length; i++) { data[i] = i; }
  29
  30 parser.encodePacket({ type: 'message', data: data }, function(encoded) {
  31   var decodedData = parser.decodePacket(encoded); // { type: 'message', data: data }
  32 });
  33 ```
  34
  35 ### With browserify
  36
  37 Engine.IO Parser is a commonjs module, which means you can include it by using
  38 `require` on the browser and package using [browserify](http://browserify.org/):
  39
  40 1. install the parser package
  41
  42     ```shell
  43     npm install engine.io-parser
  44     ```
  45
  46 1. write your app code
  47
  48     ```js
  49     var parser = require('engine.io-parser');
  50
  51     var testBuffer = new Int8Array(10);
  52     for (var i = 0; i < testBuffer.length; i++) testBuffer[i] = i;
  53
  54     var packets = [{ type: 'message', data: testBuffer.buffer }, { type: 'message', data: 'hello' }];
  55
  56     parser.encodePayload(packets, function(encoded) {
  57       parser.decodePayload(encoded,
  58         function(packet, index, total) {
  59           var isLast = index + 1 == total;
  60           if (!isLast) {
  61             var buffer = new Int8Array(packet.data); // testBuffer
  62           } else {
  63             var message = packet.data; // 'hello'
  64           }
  65         });
  66     });
  67     ```
  68
  69 1. build your app bundle
  70
  71     ```bash
  72     $ browserify app.js > bundle.js
  73     ```
  74
  75 1. include on your page
  76
  77     ```html
  78     <script src="/path/to/bundle.js"></script>
  79     ```
  80
  81 ## Features
  82
  83 - Runs on browser and node.js seamlessly
  84 - Runs inside HTML5 WebWorker
  85 - Can encode and decode packets
  86   - Encodes from/to ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer in Node
  87
  88 ## API
  89
  90 Note: `cb(type)` means the type is a callback function that contains a parameter of type `type` when called.
  91
  92 ### Node
  93
  94 - `encodePacket`
  95     - Encodes a packet.
  96     - **Parameters**
  97       - `Object`: the packet to encode, has `type` and `data`.
  98         - `data`: can be a `String`, `Number`, `Buffer`, `ArrayBuffer`
  99       - `Boolean`: optional, binary support
 100       - `Function`: callback, returns the encoded packet (`cb(String)`)
 101 - `decodePacket`
 102     - Decodes a packet. Data also available as an ArrayBuffer if requested.
 103     - Returns data as `String` or (`Blob` on browser, `ArrayBuffer` on Node)
 104     - **Parameters**
 105       - `String` | `ArrayBuffer`: the packet to decode, has `type` and `data`
 106       - `String`: optional, the binary type
 107
 108 - `encodeBase64Packet`
 109     - Encodes a packet with binary data in a base64 string (`String`)
 110     - **Parameters**
 111       - `Object`: the packet to encode, has `type` and `data`
 112       - `Function`: callback, returns the base64 encoded message (`cb(String)`)
 113 - `decodeBase64Packet`
 114     - Decodes a packet encoded in a base64 string.
 115     - **Parameters**
 116       - `String`: the base64 encoded message
 117       - `String`: optional, the binary type
 118
 119 - `encodePayload`
 120     - Encodes multiple messages (payload).
 121     - If any contents are binary, they will be encoded as base64 strings. Base64
 122       encoded strings are marked with a b before the length specifier
 123     - **Parameters**
 124       - `Array`: an array of packets
 125       - `Boolean`: optional, binary support
 126       - `Function`: callback, returns the encoded payload (`cb(String)`)
 127 - `decodePayload`
 128     - Decodes data when a payload is maybe expected. Possible binary contents are
 129       decoded from their base64 representation.
 130     - **Parameters**
 131       - `String`: the payload
 132       - `String`: optional, the binary type
 133       - `Function`: callback, returns (cb(`Object`: packet, `Number`:packet index, `Number`:packet total))
 134
 135 - `encodePayloadAsBinary`
 136     - Encodes multiple messages (payload) as binary.
 137     - **Parameters**
 138       - `Array`: an array of packets
 139       - `Function`: callback, returns the encoded payload (`cb(Buffer)`)
 140 - `decodePayloadAsBinary`
 141     - Decodes data when a payload is maybe expected. Strings are decoded by
 142       interpreting each byte as a key code for entries marked to start with 0. See
 143       description of encodePayloadAsBinary.
 144     - **Parameters**
 145       - `Buffer`: the buffer
 146       - `String`: optional, the binary type
 147       - `Function`: callback, returns the decoded packet (`cb(Object)`)
 148
 149 ### Browser
 150
 151 - `encodePayloadAsArrayBuffer`
 152     - Encodes multiple messages (payload) as binary.
 153     - **Parameters**
 154       - `Array`: an array of packets
 155       - `Function`: callback, returns the encoded payload (`cb(ArrayBuffer)`)
 156 - `encodePayloadAsBlob`
 157     - Encodes multiple messages (payload) as blob.
 158     - **Parameters**
 159       - `Array`: an array of packets
 160       - `Function`: callback, returns the encoded payload (`cb(Blob)`)
 161
 162 ## Tests
 163
 164 Standalone tests can be run with `make test` which will run both node.js and browser tests.
 165
 166 Browser tests are run using [zuul](https://github.com/defunctzombie/zuul).
 167 (You must have zuul setup with a saucelabs account.)
 168
 169 You can run the tests locally using the following command:
 170
 171 ```
 172 ./node_modules/.bin/zuul --local 8080 -- test/index.js
 173 ```
 174
 175 ## Support
 176
 177 The support channels for `engine.io-parser` are the same as `socket.io`:
 178   - irc.freenode.net **#socket.io**
 179   - [Google Groups](http://groups.google.com/group/socket_io)
 180   - [Website](http://socket.io)
 181
 182 ## Development
 183
 184 To contribute patches, run tests or benchmarks, make sure to clone the
 185 repository:
 186
 187 ```bash
 188 git clone git://github.com/LearnBoost/engine.io-parser.git
 189 ```
 190
 191 Then:
 192
 193 ```bash
 194 cd engine.io-parser
 195 npm install
 196 ```
 197
 198 See the `Tests` section above for how to run tests before submitting any patches.
 199
 200 ## License
 201
 202 MIT