engine.io-binary.events v1.0.2

engine.io-binary.events

engine.io-binary.events adds an event system to be used with the engine.io server/client library while sending binary data.

Installing

npm install engine.io-binary.events

To run client-side, copy the binary.events.js file from /lib

How To Use

Create an Event list

These events must be shared by both the client and server!

//events to be sent server-side
var server_events = [
    'server_update_position',
    'server_object_hit'
];
//events to be sent client-side
var client_events = [
    'client_move',
    'client_jump'
];

Server - Sending/Receiving

var engine = require('engine.io');
var BinaryEvents = require('engine.io-binary.events')(server_events, client_events);
var server = engine.listen(80);

server.on('connection', function(socket){
    //if only receiving binary data
    socket.on('message', BinaryEvents.onBinaryEvent);
    //or if you need to check for other types of data
    socket.on('message', function(data){
        if(data instanceof Buffer){
            BinaryEvents.onBinaryEvent.call(socket, data);
        }
    });

    //register your events in defined client_events
    socket.on('client_jump', function(buf){
        //the buffer will still contain the index of the client event in the first byte
        //buf.readUInt8(0) = index of client_jump in client_events(1 in this case)
    });
    socket.on('client_move', function(buf){});

    //creates a buffer with a length of 4 bytes(excluding the event index byte)
    var buf = BinaryEvents.createBuffer('server_update_position', 4);
    //if using default options the first byte of the buffer will contain the event index
    //make sure not to overwrite this
    //add some data
    buf.writeUInt16LE(1, 100);
    buf.writeUInt16LE(3, 300);
    socket.send(buf);
});

Client - Sending/Receiving

<script src="/path/to/engine.io.js"></script>
<script src="/path/to/binary.events.js"></script>
<script>
  // eio = Socket
  var socket = eio('ws://localhost');
  var BinaryEvents = eioBE(client_events, server_events);
  socket.on('open', function(){
    socket.on('message', BinaryEvents.onBinaryEvent);
    socket.on('server_update_position', function(buf){
        //the first byte will contain the event index
        var dv = new DataView(buf);
        dv.getUint16(1);
        dv.getUint16(3);
    });
    //send ArrayBuffer with client_jump event
    var buf = BinaryEvents.createBuffer('client_jump', 1);
    var dv = new DataView(buf);
    dv.setUint8(1, 40);
    socket.send(buf);
  });
</script>

API

Top Level

Node.js

require('engine.io-binary.events') returns a BinaryEventsManagerconstructor(see below).

Browser/Client Side

window.eioBE is a BinaryEventsManager constructor(see below).

BinaryEventsManager

Constructor

• (send_events, receive_events [, options])
  • Returns a new BinaryEventsManager instance.
  • Parameters
    • send_events: an array of strings. These are the event names you'll be sending.
    • receive_events: an array of strings. These are the event names you'll be receiving.
    • options: optional, options object.
    • Options
      • event_byte_len: Defaults to 1. The amount of bytes the event will use. If you need more than 256 events use 2 bytes.
      • litte_endian: Defaults to false. If true the event index is stored and read as little endian.

Properties

• options: returns a read only object.

Methods

• createBuffer( event_name, length )
  • Returns: ArrayBuffer(client) or Buffer(Node.js)
  • Parameters
    • event_name: One of the events in send_events.
    • length: The amount of bytes the buffer will have.
• onBinaryEvent(data)
  • Fires any event attached to the Socket with a matching receiving event index.
  • Context: must have Socket as its calling object. See examples above.
  • Parameters
    • data: any data received from the Socket message event.

Testing

Tests can be run with Node.js using npm test

There is also a server-client test in tests/server. Start the server with node server and then open server_client_test.html with a browser.

How It Works

enigine.io-binary.events works by adding an identifier – in this case a number – to the beginning of any binary data you send. This identifier will be the index of an event name in one of the arrays you provide when loading the library.

When the data is received, the identifier is stripped and the index is matched to an event name - that event is then fired.

As the event names are referenced on both the client and server-side, it is of most importance that the arrays of these event names are identical.