engine.io-binary.events
adds an event system to be used with the engine.io server/client library while sending binary data.
npm install engine.io-binary.events
To run client-side, copy the binary.events.js
file from /lib
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'
];
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);
});
<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>
require('engine.io-binary.events')
returns a BinaryEventsManager
constructor(see below).
window.eioBE
is a BinaryEventsManager
constructor(see below).
-
(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.
-
-
- Returns a new
-
options
: returns a read only object.
-
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.
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.
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.