websoket/node_modules/binaryjs/doc/api.md

BinaryJS API Reference

Class: binaryjs.BinaryServer Node.js only

This class is a the BinaryJS websocket server. It is an EventEmitter.

new binaryjs.BinaryServer([options], [callback])

• options Object
  • host String. Default 0.0.0.0
  • port Number
  • server Object. Use an existing http.Server or ws.Server instead of creating a new one.
  • path String. The path on which to accept WebSocket connections
  • chunkSize Number. Passed into constructor of connecting BinaryClient. Default 40960

Construct a new server object.

Either port must be provided or server to use an existing http.Server.

server.clients

A hash of all connected clients. Keys are client ids and values are instances of binaryjs.BinaryClient.

server.close()

Close the server and terminate all clients.

Event: 'error'

function (error) { }

If the underlying server emits an error, it will be forwarded here.

Event: 'connection'

function (client) { }

When a new BinaryJS connection is established. client is an object of type binaryjs.BinaryClient.

Class: binaryjs.BinaryClient Node.js and browsers

This class represents a BinaryJS websocket client connection. It is an EventEmitter.

new binaryjs.BinaryClient(address, [options])

Connects to the given address (in the form ws://url).

• options Object
  • chunkSize Number. Size of chunks when using client.send. Default 40960

BinaryClient can also be obtained in the connection event of a BinaryServer

client.streams

A hash of all current streams. Keys are stream ids and values are instances of binaryjs.BinaryStream.

client.createStream([meta])

Returns binaryjs.BinaryStream

Creates a new readable and writable binaryjs.BinaryStream object, triggering a stream event on the remote client with the given meta data parameter.

client.send(data, [meta])

Returns binaryjs.BinaryStream

Creates a new readable and writable binaryjs.BinaryStream object with the given meta data and sends data through the connection.

If data is a Node.js Buffer or browser ArrayBuffer, ArrayBufferView, Blob, or File, the data will be chunked according to options.chunkSize and streamed through the new BinaryStream.

If data is a Node.js stream (including BinaryStream objects), it will be piped into a new BinaryStream

If data is any other type, it will be sent through the stream in one chunk.

client.close()

Gracefully closes the connection.

Event: 'stream'

function (stream, meta) { }

Emitted when a new stream is initialized by the remote client.

stream is a binaryjs.BinaryStream object that is both readable and writable.

meta is the data given when the stream was created via createStream(meta) or send(data, meta), sent verbatim.

Event: 'error'

function (error) { }

If the client emits an error, this event is emitted (errors from the underlying net.Socket are forwarded here).

Event: 'close'

function () { }

Is emitted when the connection is closed.

The close event is also emitted when then underlying net.Socket closes the connection (end or close).

Event: 'open'

function () { }

Emitted when the connection is established.

Class: binaryjs.BinaryStream Node.js and browsers

This class represents a BinaryJS client stream. It is a Node.js Stream and EventEmitter.

BinaryStreams are created through the BinaryClient createStream and send methods and received through the stream event.

Because BinaryStream extends the Node.js stream, all other streams can be piped into or from a BinaryStream. The browser implements a browser version of the Node.js stream API.

stream.id

A id number identifying the stream. Unique to the given client, but not globally.

stream.readable

Whether stream is readable.

stream.writable

Whether stream is writable.

stream.paused

Whether stream is paused.

stream.pause()

Pause the stream.

stream.resume()

Resume the stream.

stream.end()

Sends an end message, triggering the end event and marks stream.readable false but does not close the socket.

stream.write(data)

Returns true if data is written immediately or false if data is buffered in socket.

Writes data through the connection. data can be any JSON compatible type or binary data. Note data will not be chunked. client.send should be used for chunking.

stream.destroy()

Immediately closed the socket.

stream.pipe(destination, [options])

This is a Stream.prototype method available on all Streams.

See: http://nodejs.org/api/stream.html#stream_stream_pipe_destination_options

Event: 'data'

function (data) { }

Is emitted when data is received through the socket.

For non-binary types, data is received verbatim as sent.

On Node.js, binary data is received as Buffer.

On browsers, binary data is received as ArrayBuffer.

Event: 'pause'

function () { }

Is emitted when stream is paused.

Event: 'resume'

function () { }

Is emitted when stream is resumed.

Event: 'end'

function () { }

Is emitted when stream.end has been called. stream.readable is set to false.

Event: 'close'

function () { }

Emitted when the connection is destroyed or its underlying socket is closed.

Event: 'drain'

function () { }

Emitted when the underlying socket buffer has drained. Used for stream pipe internals.

Event: 'error'

function (error) { }

If the client emits an error, this event is emitted (errors from the underlying net.Socket are forwarded here). stream.readable and stream.writable are set to false.