# 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`.