diff node_modules/socket.io/Readme.md @ 76:0ae87af84e2f

added oscgroups

--- a/node_modules/socket.io/Readme.md	Tue Jul 01 08:51:53 2014 +0000
+++ b/node_modules/socket.io/Readme.md	Sun Jul 13 10:07:41 2014 +0100
@@ -1,364 +1,346 @@
-# Socket.IO
 
-Socket.IO is a Node.JS project that makes WebSockets and realtime possible in
-all browsers. It also enhances WebSockets by providing built-in multiplexing,
-horizontal scalability, automatic JSON encoding/decoding, and more.
+# socket.io
 
-## How to Install
-
-```bash
-npm install socket.io
-```
+[![Build Status](https://secure.travis-ci.org/Automattic/socket.io.png)](http://travis-ci.org/Automattic/socket.io)
+[![NPM version](https://badge.fury.io/js/socket.io.png)](http://badge.fury.io/js/socket.io)
 
 ## How to use
 
-First, require `socket.io`:
+The following example attaches socket.io to a plain Node.JS
+HTTP server listening on port `3000`.
 
 ```js
-var io = require('socket.io');
+var server = require('http').Server();
+var io = require('socket.io')(server);
+io.on('connection', function(socket){
+  socket.on('event', function(data){});
+  socket.on('disconnect', function(){});
+});
+server.listen(3000);
 ```
 
-Next, attach it to a HTTP/HTTPS server. If you're using the fantastic `express`
-web framework:
-
-#### Express 3.x
+### Standalone
 
 ```js
-var app = express()
-  , server = require('http').createServer(app)
-  , io = io.listen(server);
-
-server.listen(80);
-
-io.sockets.on('connection', function (socket) {
-  socket.emit('news', { hello: 'world' });
-  socket.on('my other event', function (data) {
-    console.log(data);
-  });
-});
+var io = require('socket.io')();
+io.on('connection', function(socket){});
+io.listen(3000);
 ```
 
-#### Express 2.x
+### In conjunction with Express
+
+Starting with **3.0**, express applications have become request handler
+functions that you pass to `http` or `http` `Server` instances. You need
+to pass the `Server` to `socket.io`, and not the express application
+function.
 
 ```js
-var app = express.createServer()
-  , io = io.listen(app);
-
-app.listen(80);
-
-io.sockets.on('connection', function (socket) {
-  socket.emit('news', { hello: 'world' });
-  socket.on('my other event', function (data) {
-    console.log(data);
-  });
-});
+var app = require('express')();
+var server = require('http').Server(app);
+var io = require('socket.io')(server);
+io.on('connection', function(){ /* … */ });
+server.listen(3000);
 ```
 
-Finally, load it from the client side code:
+### In conjunction with Koa
 
-```html
-<script src="/socket.io/socket.io.js"></script>
-<script>
-  var socket = io.connect('http://localhost');
-  socket.on('news', function (data) {
-    console.log(data);
-    socket.emit('my other event', { my: 'data' });
-  });
-</script>
+Like Express.JS, Koa works by exposing an application as a request
+handler function, but only by calling the `callback` method.
+
+```js
+var app = require('koa')();
+var server = require('http').Server(app.callback());
+var io = require('socket.io')(server);
+io.on('connection', function(){ /* … */ });
+server.listen(3000);
 ```
 
-For more thorough examples, look at the `examples/` directory.
+## API
 
-## Short recipes
+### Server
 
-### Sending and receiving events.
+  Exposed by `require('socket.io')`.
 
-Socket.IO allows you to emit and receive custom events.
-Besides `connect`, `message` and `disconnect`, you can emit custom events:
+### Server()
 
-```js
-// note, io.listen(<port>) will create a http server for you
-var io = require('socket.io').listen(80);
+  Creates a new `Server`. Works with and without `new`:
 
-io.sockets.on('connection', function (socket) {
-  io.sockets.emit('this', { will: 'be received by everyone' });
+  ```js
+  var io = require('socket.io')();
+  // or
+  var Server = require('socket.io');
+  var io = new Server();
+  ```
 
-  socket.on('private message', function (from, msg) {
-    console.log('I received a private message by ', from, ' saying ', msg);
+### Server(opts:Object)
+
+  Optionally, the first or second argument (see below) of the `Server`
+  constructor can be an options object.
+
+  The following options are supported:
+
+  - `serveClient` sets the value for Server#serveClient()
+  - `path` sets the value for Server#path()
+
+  The same options passed to socket.io are always passed to
+  the `engine.io` `Server` that gets created. See engine.io
+  [options](https://github.com/learnboost/engine.io#methods-1)
+  as reference.
+
+### Server(srv:http#Server, opts:Object)
+
+  Creates a new `Server` and attaches it to the given `srv`. Optionally
+  `opts` can be passed.
+
+### Server(port:Number, opts:Object)
+
+  Binds socket.io to a new `http.Server` that listens on `port`.
+
+### Server#serveClient(v:Boolean):Server
+
+  If `v` is `true` the attached server (see `Server#attach`) will serve
+  the client files. Defaults to `true`.
+
+  This method has no effect after `attach` is called.
+
+  ```js
+  // pass a server and the `serveClient` option
+  var io = require('socket.io')(http, { serveClient: false });
+
+  // or pass no server and then you can call the method
+  var io = require('socket.io')();
+  io.serveClient(false);
+  io.attach(http);
+  ```
+
+  If no arguments are supplied this method returns the current value.
+
+### Server#path(v:String):Server
+
+  Sets the path `v` under which `engine.io` and the static files will be
+  served. Defaults to `/socket.io`.
+
+  If no arguments are supplied this method returns the current value.
+
+### Server#adapter(v:Adapter):Server
+
+  Sets the adapter `v`. Defaults to an instance of the `Adapter` that
+  ships with socket.io which is memory based. See
+  [socket.io-adapter](https://github.com/Automattic/socket.io-adapter).
+
+  If no arguments are supplied this method returns the current value.
+
+### Server#origins(v:String):Server
+
+  Sets the allowed origins `v`. Defaults to any origins being allowed.
+
+  If no arguments are supplied this method returns the current value.
+
+
+### Server#sockets:Namespace
+
+  The default (`/`) namespace.
+
+### Server#attach(srv:http#Server, opts:Object):Server
+
+  Attaches the `Server` to an engine.io instance on `srv` with the
+  supplied `opts` (optionally).
+
+### Server#attach(port:Number, opts:Object):Server
+
+  Attaches the `Server` to an engine.io instance that is bound to `port`
+  with the given `opts` (optionally).
+
+### Server#listen
+
+  Synonym of `Server#attach`.
+
+### Server#bind(srv:engine#Server):Server
+
+  Advanced use only. Binds the server to a specific engine.io `Server` 
+  (or compatible API) instance.
+
+### Server#onconnection(socket:engine#Socket):Server
+
+  Advanced use only. Creates a new `socket.io` client from the incoming
+  engine.io (or compatible API) `socket`.
+
+### Server#of(nsp:String):Namespace
+
+  Initializes and retrieves the given `Namespace` by its pathname 
+  identifier `nsp`.
+
+  If the namespace was already initialized it returns it right away.
+
+### Server#emit
+
+  Emits an event to all connected clients. The following two are 
+  equivalent:
+
+  ```js
+  var io = require('socket.io')();
+  io.sockets.emit('an event sent to all connected clients');
+  io.emit('an event sent to all connected clients');
+  ```
+
+  For other available methods, see `Namespace` below.
+
+### Server#use
+
+  See `Namespace#use` below.
+
+### Namespace
+
+  Represents a pool of sockets connected under a given scope identified
+  by a pathname (eg: `/chat`).
+
+  By default the client always connects to `/`.
+
+#### Events
+
+  - `connection` / `connect`. Fired upon a connection.
+
+    Parameters:
+    - `Socket` the incoming socket.
+
+### Namespace#name:String
+
+  The namespace identifier property.
+
+### Namespace#connected:Object<Socket>
+
+  Hash of `Socket` objects that are connected to this namespace indexed
+  by `id`.
+
+### Namespace#use(fn:Function):Namespace
+
+  Registers a middleware, which is a function that gets executed for
+  every incoming `Socket` and receives as parameter the socket and a
+  function to optionally defer execution to the next registered
+  middleware.
+
+  ```js
+  var io = require('socket.io')();
+  io.use(function(socket, next){
+    if (socket.request.headers.cookie) return next();
+    next(new Error('Authentication error'));
   });
+  ```
 
-  socket.on('disconnect', function () {
-    io.sockets.emit('user disconnected');
+  Errors passed to middleware callbacks are sent as special `error`
+  packets to clients.
+
+### Socket
+
+  A `Socket` is the fundamental class for interacting with browser
+  clients. A `Socket` belongs to a certain `Namespace` (by default `/`)
+  and uses an underlying `Client` to communicate.
+
+### Socket#rooms:Array
+
+  A list of strings identifying the rooms this socket is in.
+
+### Socket#client:Client
+
+  A reference to the underlying `Client` object.
+
+### Socket#conn:Socket
+
+  A reference to the underyling `Client` transport connection (engine.io
+  `Socket` object).
+
+### Socket#request:Request
+
+  A getter proxy that returns the reference to the `request` that
+  originated the underlying engine.io `Client`. Useful for accessing
+  request headers such as `Cookie` or `User-Agent`.
+
+### Socket#id:String
+
+  A unique identifier for the socket session, that comes from the
+  underlying `Client`.
+
+### Socket#emit(name:String[, …]):Socket
+
+  Emits an event to the socket identified by the string `name`. Any
+  other parameters can be included.
+
+  All datastructures are supported, including `Buffer`. JavaScript
+  functions can't be serialized/deserialized.
+
+  ```js
+  var io = require('socket.io')();
+  io.on('connection', function(socket){
+    socket.emit('an event', { some: 'data' });
   });
-});
+  ```
+
+### Socket#join(name:String[, fn:Function]):Socket
+
+  Adds the socket to the `room`, and fires optionally a callback `fn`
+  with `err` signature (if any).
+
+  The socket is automatically a member of a room identified with its
+  session id (see `Socket#id`).
+
+  The mechanics of joining  rooms are handled by the `Adapter`
+  that has been configured (see `Server#adapter` above), defaulting to
+  [socket.io-adapter](https://github.com/Automattic/socket.io-adapter).
+
+### Socket#leave(name:String[, fn:Function]):Socket
+
+  Removes the socket from `room`, and fires optionally a callback `fn`
+  with `err` signature (if any).
+
+  **Rooms are left automatically upon disconnection**.
+
+  The mechanics of leaving rooms are handled by the `Adapter`
+  that has been configured (see `Server#adapter` above), defaulting to
+  [socket.io-adapter](https://github.com/Automattic/socket.io-adapter).
+
+### Socket#to(room:String):Socket
+### Socket#in(room:String):Socket
+
+  Sets a modifier for a subsequent event emission that the event will
+  only be _broadcasted_ to sockets that have joined the given `room`.
+
+  To emit to multiple rooms, you can call `to` several times.
+
+  ```js
+  var io = require('socket.io')();
+  io.on('connection', function(socket){
+    socket.to('others').emit('an event', { some: 'data' });
+  });
+  ```
+
+### Client
+
+  The `Client` class represents an incoming transport (engine.io)
+  connection. A `Client` can be associated with many multiplexed `Socket`
+  that belong to different `Namespace`s.
+
+### Client#conn
+
+  A reference to the underlying `engine.io` `Socket` connection.
+
+### Client#request
+
+  A getter proxy that returns the reference to the `request` that
+  originated the engine.io connection. Useful for accessing
+  request headers such as `Cookie` or `User-Agent`.
+
+## Debug / logging
+
+Socket.IO is powered by [debug](http://github.com/visionmedia/debug).
+In order to see all the debug output, run your app with the environment variable
+`DEBUG` including the desired scope.
+
+To see the output from all of Socket.IO's debugging scopes you can use:
+
+```
+DEBUG=socket.io* node myapp
 ```
 
-### Storing data associated to a client
+## License
 
-Sometimes it's necessary to store data associated with a client that's
-necessary for the duration of the session.
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-io.sockets.on('connection', function (socket) {
-  socket.on('set nickname', function (name) {
-    socket.set('nickname', name, function () { socket.emit('ready'); });
-  });
-
-  socket.on('msg', function () {
-    socket.get('nickname', function (err, name) {
-      console.log('Chat message by ', name);
-    });
-  });
-});
-```
-
-#### Client side
-
-```html
-<script>
-  var socket = io.connect('http://localhost');
-
-  socket.on('connect', function () {
-    socket.emit('set nickname', prompt('What is your nickname?'));
-    socket.on('ready', function () {
-      console.log('Connected !');
-      socket.emit('msg', prompt('What is your message?'));
-    });
-  });
-</script>
-```
-
-### Restricting yourself to a namespace
-
-If you have control over all the messages and events emitted for a particular
-application, using the default `/` namespace works.
-
-If you want to leverage 3rd-party code, or produce code to share with others,
-socket.io provides a way of namespacing a `socket`.
-
-This has the benefit of `multiplexing` a single connection. Instead of
-socket.io using two `WebSocket` connections, it'll use one.
-
-The following example defines a socket that listens on '/chat' and one for
-'/news':
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-var chat = io
-  .of('/chat')
-  .on('connection', function (socket) {
-    socket.emit('a message', { that: 'only', '/chat': 'will get' });
-    chat.emit('a message', { everyone: 'in', '/chat': 'will get' });
-  });
-
-var news = io
-  .of('/news');
-  .on('connection', function (socket) {
-    socket.emit('item', { news: 'item' });
-  });
-```
-
-#### Client side:
-
-```html
-<script>
-  var chat = io.connect('http://localhost/chat')
-    , news = io.connect('http://localhost/news');
-
-  chat.on('connect', function () {
-    chat.emit('hi!');
-  });
-
-  news.on('news', function () {
-    news.emit('woot');
-  });
-</script>
-```
-
-### Sending volatile messages.
-
-Sometimes certain messages can be dropped. Let's say you have an app that
-shows realtime tweets for the keyword `bieber`. 
-
-If a certain client is not ready to receive messages (because of network slowness
-or other issues, or because he's connected through long polling and is in the
-middle of a request-response cycle), if he doesn't receive ALL the tweets related
-to bieber your application won't suffer.
-
-In that case, you might want to send those messages as volatile messages.
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-io.sockets.on('connection', function (socket) {
-  var tweets = setInterval(function () {
-    getBieberTweet(function (tweet) {
-      socket.volatile.emit('bieber tweet', tweet);
-    });
-  }, 100);
-
-  socket.on('disconnect', function () {
-    clearInterval(tweets);
-  });
-});
-```
-
-#### Client side
-
-In the client side, messages are received the same way whether they're volatile
-or not.
-
-### Getting acknowledgements
-
-Sometimes, you might want to get a callback when the client confirmed the message
-reception.
-
-To do this, simply pass a function as the last parameter of `.send` or `.emit`.
-What's more, when you use `.emit`, the acknowledgement is done by you, which
-means you can also pass data along:
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-io.sockets.on('connection', function (socket) {
-  socket.on('ferret', function (name, fn) {
-    fn('woot');
-  });
-});
-```
-
-#### Client side
-
-```html
-<script>
-  var socket = io.connect(); // TIP: .connect with no args does auto-discovery
-  socket.on('connect', function () { // TIP: you can avoid listening on `connect` and listen on events directly too!
-    socket.emit('ferret', 'tobi', function (data) {
-      console.log(data); // data will be 'woot'
-    });
-  });
-</script>
-```
-
-### Broadcasting messages
-
-To broadcast, simply add a `broadcast` flag to `emit` and `send` method calls.
-Broadcasting means sending a message to everyone else except for the socket
-that starts it.
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-io.sockets.on('connection', function (socket) {
-  socket.broadcast.emit('user connected');
-  socket.broadcast.json.send({ a: 'message' });
-});
-```
-
-### Rooms
-
-Sometimes you want to put certain sockets in the same room, so that it's easy
-to broadcast to all of them together.
-
-Think of this as built-in channels for sockets. Sockets `join` and `leave`
-rooms in each socket.
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-io.sockets.on('connection', function (socket) {
-  socket.join('justin bieber fans');
-  socket.broadcast.to('justin bieber fans').emit('new fan');
-  io.sockets.in('rammstein fans').emit('new non-fan');
-});
-```
-
-### Using it just as a cross-browser WebSocket
-
-If you just want the WebSocket semantics, you can do that too.
-Simply leverage `send` and listen on the `message` event:
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-io.sockets.on('connection', function (socket) {
-  socket.on('message', function () { });
-  socket.on('disconnect', function () { });
-});
-```
-
-#### Client side
-
-```html
-<script>
-  var socket = io.connect('http://localhost/');
-  socket.on('connect', function () {
-    socket.send('hi');
-
-    socket.on('message', function (msg) {
-      // my msg
-    });
-  });
-</script>
-```
-
-### Changing configuration
-
-Configuration in socket.io is TJ-style:
-
-#### Server side
-
-```js
-var io = require('socket.io').listen(80);
-
-io.configure(function () {
-  io.set('transports', ['websocket', 'flashsocket', 'xhr-polling']);
-});
-
-io.configure('development', function () {
-  io.set('transports', ['websocket', 'xhr-polling']);
-  io.enable('log');
-});
-```
-
-## License 
-
-(The MIT License)
-
-Copyright (c) 2011 Guillermo Rauch &lt;[e-mail]&gt;
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MIT