169 lines
5.3 KiB
Markdown
169 lines
5.3 KiB
Markdown
# Getting Started with BinaryJS
|
|
|
|
In this guide we'll download, install, and then build the [helloworld](https://github.com/binaryjs/binaryjs/tree/master/examples/helloworld) example. In this example we send clients a picture of a flower by piping the file into a binary websocket;
|
|
|
|
## Download
|
|
|
|
1. Install the BinaryJS server
|
|
|
|
```console
|
|
$ npm install binaryjs
|
|
```
|
|
or from Git
|
|
```console
|
|
$ git://github.com/binaryjs/binaryjs.git
|
|
$ cd binaryjs
|
|
$ npm install -g
|
|
```
|
|
|
|
2. Get the latest client library for your webpage
|
|
|
|
```html
|
|
<script src="http://cdn.binaryjs.com/0/binary.js"></script>
|
|
```
|
|
|
|
## Create the server
|
|
[View complete server.js source](https://github.com/binaryjs/binaryjs/blob/master/examples/helloworld/server.js)
|
|
|
|
First we include BinaryJS and the fs module
|
|
|
|
```js
|
|
var BinaryServer = require('binaryjs').BinaryServer;
|
|
var fs = require('fs');
|
|
```
|
|
|
|
Then we create a new server, specifying that we want to run it on port 9000:
|
|
|
|
```js
|
|
var server = BinaryServer({port: 9000});
|
|
```
|
|
|
|
Now we'll add a callback for new client connections
|
|
|
|
```js
|
|
server.on('connection', function(client){
|
|
//
|
|
});
|
|
```
|
|
|
|
Let's add to that callback so when a client connects, we'll send them a picture as a hello world
|
|
|
|
```js
|
|
server.on('connection', function(client){
|
|
var file = fs.createReadStream(__dirname + '/flower.png');
|
|
client.send(file);
|
|
});
|
|
```
|
|
|
|
Note that instead of `client.send(file)` we could've done this:
|
|
|
|
```js
|
|
var stream = client.createStream();
|
|
file.pipe(stream);
|
|
```
|
|
|
|
`client.send` is a helper function for doing just that when it takes a stream parameter, note that behavior is different for other parameter types. [See API reference](https://github.com/binaryjs/binaryjs/blob/master/doc/api.md#clientsenddata-meta).
|
|
|
|
That's it for the server!
|
|
|
|
## Create the client
|
|
[View complete index.html source](https://github.com/binaryjs/binaryjs/blob/master/examples/helloworld/index.html)
|
|
|
|
Make sure to include the client library, served by the cdn
|
|
|
|
```html
|
|
<script src="http://cdn.binaryjs.com/0/binary.js"></script>
|
|
```
|
|
|
|
Now here's our client side Javascript so we can receive that file
|
|
|
|
First we connection the server we just created
|
|
|
|
```js
|
|
var client = new BinaryClient('ws://localhost:9000');
|
|
```
|
|
|
|
Then we'll add a callback for the `stream` event, which is emitted when the server sends us the flower file stream.
|
|
|
|
```js
|
|
client.on('stream', function(stream, meta){
|
|
//
|
|
});
|
|
```
|
|
|
|
Now to finish up, inside that callback we need to do several things:
|
|
* Create an array to hold the parts of the image
|
|
* Add to array on the stream `data` event
|
|
* Create an `<img>` element and set the src to the data
|
|
|
|
```js
|
|
client.on('stream', function(stream, meta){
|
|
var parts = [];
|
|
stream.on('data', function(data){
|
|
parts.push(data);
|
|
});
|
|
stream.on('end', function(){
|
|
var img = document.createElement("img");
|
|
img.src = (window.URL || window.webkitURL).createObjectURL(new Blob(parts));
|
|
document.body.appendChild(img);
|
|
});
|
|
});
|
|
```
|
|
|
|
## Integrating with an existing node app
|
|
BinaryServer can listen on an existing [http.Server](http://nodejs.org/api/http.html#http_class_http_server) by specifying the `server` parameter in the options. See [fileupload](https://github.com/binaryjs/binaryjs/tree/master/examples/fileupload) example of this.
|
|
|
|
```js
|
|
var http = require('http');
|
|
var server = http.createServer(function (req, res) {
|
|
res.writeHead(200, {'Content-Type': 'text/plain'});
|
|
res.end('Hello World\n');
|
|
}).listen(9000);
|
|
|
|
var BinaryServer = require('binaryjs').BinaryServer,
|
|
fs = require('fs');
|
|
|
|
// Create a BinaryServer attached to our existing server
|
|
var binaryserver = new BinaryServer({server: server, path: '/binary-endpoint'});
|
|
|
|
binaryserver.on('connection', function(client){
|
|
var file = fs.createReadStream(__dirname + '/flower.png');
|
|
client.send(file);
|
|
});
|
|
```
|
|
|
|
Note that we've also supplied `path: 'binary-endpoint'` to set an endpoint that doesn't clash with the original application. When creating the client you can connect to this endpoint with:
|
|
|
|
```js
|
|
var client = new BinaryClient('ws://localhost:9000/binary-endpoint');
|
|
```
|
|
|
|
### Express.js
|
|
|
|
If your app runs on express js - the normal `app.listen(9000)` won't give you access to the base http server, instead you should create the a server and pass the express app as a request listener:
|
|
|
|
```js
|
|
var http = require('http');
|
|
var app = require('express')();
|
|
|
|
// create a server with the express app as a listener
|
|
var server = http.createServer(app).listen(9000);
|
|
|
|
// attach BinaryServer to the base http server
|
|
```
|
|
|
|
|
|
## Running the example
|
|
Run the server, and open index.html in your favorite binary socket compatible browser, and you'll see a lovely flower!
|
|
|
|
## Additonal details
|
|
This example shows you how to include the server and client BinaryJS libraries and stream your first piece of data.
|
|
|
|
BinaryJS is extremely flexible. You aren't limited to sending only binary data. In fact you can send any JSON compatible type and take advantage of the compact BinaryPack serialization format.
|
|
|
|
You aren't limited to piping streams around either. You can create as many streams as you want for each client, and send data bidirectionally, whether its a large buffer at once, chunked, or just strings and numbers and arrays and hashes.
|
|
|
|
[Check out the API reference](https://github.com/binaryjs/binaryjs/blob/master/doc/api.md)
|
|
|
|
[Ask questions on the mailing list](http://groups.google.com/group/binaryjs-group)
|