217 lines
5.6 KiB
Markdown
217 lines
5.6 KiB
Markdown
# 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`.
|
|
|