rc-web@69: 
rob@76: # socket.io
rc-web@69: 
rob@76: [![Build Status](https://secure.travis-ci.org/Automattic/socket.io.png)](http://travis-ci.org/Automattic/socket.io)
rob@76: [![NPM version](https://badge.fury.io/js/socket.io.png)](http://badge.fury.io/js/socket.io)
rc-web@69: 
rc-web@69: ## How to use
rc-web@69: 
rob@76: The following example attaches socket.io to a plain Node.JS
rob@76: HTTP server listening on port `3000`.
rc-web@69: 
rc-web@69: ```js
rob@76: var server = require('http').Server();
rob@76: var io = require('socket.io')(server);
rob@76: io.on('connection', function(socket){
rob@76:   socket.on('event', function(data){});
rob@76:   socket.on('disconnect', function(){});
rob@76: });
rob@76: server.listen(3000);
rc-web@69: ```
rc-web@69: 
rob@76: ### Standalone
rc-web@69: 
rc-web@69: ```js
rob@76: var io = require('socket.io')();
rob@76: io.on('connection', function(socket){});
rob@76: io.listen(3000);
rc-web@69: ```
rc-web@69: 
rob@76: ### In conjunction with Express
rob@76: 
rob@76: Starting with **3.0**, express applications have become request handler
rob@76: functions that you pass to `http` or `http` `Server` instances. You need
rob@76: to pass the `Server` to `socket.io`, and not the express application
rob@76: function.
rc-web@69: 
rc-web@69: ```js
rob@76: var app = require('express')();
rob@76: var server = require('http').Server(app);
rob@76: var io = require('socket.io')(server);
rob@76: io.on('connection', function(){ /* … */ });
rob@76: server.listen(3000);
rc-web@69: ```
rc-web@69: 
rob@76: ### In conjunction with Koa
rc-web@69: 
rob@76: Like Express.JS, Koa works by exposing an application as a request
rob@76: handler function, but only by calling the `callback` method.
rob@76: 
rob@76: ```js
rob@76: var app = require('koa')();
rob@76: var server = require('http').Server(app.callback());
rob@76: var io = require('socket.io')(server);
rob@76: io.on('connection', function(){ /* … */ });
rob@76: server.listen(3000);
rc-web@69: ```
rc-web@69: 
rob@76: ## API
rc-web@69: 
rob@76: ### Server
rc-web@69: 
rob@76:   Exposed by `require('socket.io')`.
rc-web@69: 
rob@76: ### Server()
rc-web@69: 
rob@76:   Creates a new `Server`. Works with and without `new`:
rc-web@69: 
rob@76:   ```js
rob@76:   var io = require('socket.io')();
rob@76:   // or
rob@76:   var Server = require('socket.io');
rob@76:   var io = new Server();
rob@76:   ```
rc-web@69: 
rob@76: ### Server(opts:Object)
rob@76: 
rob@76:   Optionally, the first or second argument (see below) of the `Server`
rob@76:   constructor can be an options object.
rob@76: 
rob@76:   The following options are supported:
rob@76: 
rob@76:   - `serveClient` sets the value for Server#serveClient()
rob@76:   - `path` sets the value for Server#path()
rob@76: 
rob@76:   The same options passed to socket.io are always passed to
rob@76:   the `engine.io` `Server` that gets created. See engine.io
rob@76:   [options](https://github.com/learnboost/engine.io#methods-1)
rob@76:   as reference.
rob@76: 
rob@76: ### Server(srv:http#Server, opts:Object)
rob@76: 
rob@76:   Creates a new `Server` and attaches it to the given `srv`. Optionally
rob@76:   `opts` can be passed.
rob@76: 
rob@76: ### Server(port:Number, opts:Object)
rob@76: 
rob@76:   Binds socket.io to a new `http.Server` that listens on `port`.
rob@76: 
rob@76: ### Server#serveClient(v:Boolean):Server
rob@76: 
rob@76:   If `v` is `true` the attached server (see `Server#attach`) will serve
rob@76:   the client files. Defaults to `true`.
rob@76: 
rob@76:   This method has no effect after `attach` is called.
rob@76: 
rob@76:   ```js
rob@76:   // pass a server and the `serveClient` option
rob@76:   var io = require('socket.io')(http, { serveClient: false });
rob@76: 
rob@76:   // or pass no server and then you can call the method
rob@76:   var io = require('socket.io')();
rob@76:   io.serveClient(false);
rob@76:   io.attach(http);
rob@76:   ```
rob@76: 
rob@76:   If no arguments are supplied this method returns the current value.
rob@76: 
rob@76: ### Server#path(v:String):Server
rob@76: 
rob@76:   Sets the path `v` under which `engine.io` and the static files will be
rob@76:   served. Defaults to `/socket.io`.
rob@76: 
rob@76:   If no arguments are supplied this method returns the current value.
rob@76: 
rob@76: ### Server#adapter(v:Adapter):Server
rob@76: 
rob@76:   Sets the adapter `v`. Defaults to an instance of the `Adapter` that
rob@76:   ships with socket.io which is memory based. See
rob@76:   [socket.io-adapter](https://github.com/Automattic/socket.io-adapter).
rob@76: 
rob@76:   If no arguments are supplied this method returns the current value.
rob@76: 
rob@76: ### Server#origins(v:String):Server
rob@76: 
rob@76:   Sets the allowed origins `v`. Defaults to any origins being allowed.
rob@76: 
rob@76:   If no arguments are supplied this method returns the current value.
rob@76: 
rob@76: 
rob@76: ### Server#sockets:Namespace
rob@76: 
rob@76:   The default (`/`) namespace.
rob@76: 
rob@76: ### Server#attach(srv:http#Server, opts:Object):Server
rob@76: 
rob@76:   Attaches the `Server` to an engine.io instance on `srv` with the
rob@76:   supplied `opts` (optionally).
rob@76: 
rob@76: ### Server#attach(port:Number, opts:Object):Server
rob@76: 
rob@76:   Attaches the `Server` to an engine.io instance that is bound to `port`
rob@76:   with the given `opts` (optionally).
rob@76: 
rob@76: ### Server#listen
rob@76: 
rob@76:   Synonym of `Server#attach`.
rob@76: 
rob@76: ### Server#bind(srv:engine#Server):Server
rob@76: 
rob@76:   Advanced use only. Binds the server to a specific engine.io `Server` 
rob@76:   (or compatible API) instance.
rob@76: 
rob@76: ### Server#onconnection(socket:engine#Socket):Server
rob@76: 
rob@76:   Advanced use only. Creates a new `socket.io` client from the incoming
rob@76:   engine.io (or compatible API) `socket`.
rob@76: 
rob@76: ### Server#of(nsp:String):Namespace
rob@76: 
rob@76:   Initializes and retrieves the given `Namespace` by its pathname 
rob@76:   identifier `nsp`.
rob@76: 
rob@76:   If the namespace was already initialized it returns it right away.
rob@76: 
rob@76: ### Server#emit
rob@76: 
rob@76:   Emits an event to all connected clients. The following two are 
rob@76:   equivalent:
rob@76: 
rob@76:   ```js
rob@76:   var io = require('socket.io')();
rob@76:   io.sockets.emit('an event sent to all connected clients');
rob@76:   io.emit('an event sent to all connected clients');
rob@76:   ```
rob@76: 
rob@76:   For other available methods, see `Namespace` below.
rob@76: 
rob@76: ### Server#use
rob@76: 
rob@76:   See `Namespace#use` below.
rob@76: 
rob@76: ### Namespace
rob@76: 
rob@76:   Represents a pool of sockets connected under a given scope identified
rob@76:   by a pathname (eg: `/chat`).
rob@76: 
rob@76:   By default the client always connects to `/`.
rob@76: 
rob@76: #### Events
rob@76: 
rob@76:   - `connection` / `connect`. Fired upon a connection.
rob@76: 
rob@76:     Parameters:
rob@76:     - `Socket` the incoming socket.
rob@76: 
rob@76: ### Namespace#name:String
rob@76: 
rob@76:   The namespace identifier property.
rob@76: 
rob@76: ### Namespace#connected:Object<Socket>
rob@76: 
rob@76:   Hash of `Socket` objects that are connected to this namespace indexed
rob@76:   by `id`.
rob@76: 
rob@76: ### Namespace#use(fn:Function):Namespace
rob@76: 
rob@76:   Registers a middleware, which is a function that gets executed for
rob@76:   every incoming `Socket` and receives as parameter the socket and a
rob@76:   function to optionally defer execution to the next registered
rob@76:   middleware.
rob@76: 
rob@76:   ```js
rob@76:   var io = require('socket.io')();
rob@76:   io.use(function(socket, next){
rob@76:     if (socket.request.headers.cookie) return next();
rob@76:     next(new Error('Authentication error'));
rc-web@69:   });
rob@76:   ```
rc-web@69: 
rob@76:   Errors passed to middleware callbacks are sent as special `error`
rob@76:   packets to clients.
rob@76: 
rob@76: ### Socket
rob@76: 
rob@76:   A `Socket` is the fundamental class for interacting with browser
rob@76:   clients. A `Socket` belongs to a certain `Namespace` (by default `/`)
rob@76:   and uses an underlying `Client` to communicate.
rob@76: 
rob@76: ### Socket#rooms:Array
rob@76: 
rob@76:   A list of strings identifying the rooms this socket is in.
rob@76: 
rob@76: ### Socket#client:Client
rob@76: 
rob@76:   A reference to the underlying `Client` object.
rob@76: 
rob@76: ### Socket#conn:Socket
rob@76: 
rob@76:   A reference to the underyling `Client` transport connection (engine.io
rob@76:   `Socket` object).
rob@76: 
rob@76: ### Socket#request:Request
rob@76: 
rob@76:   A getter proxy that returns the reference to the `request` that
rob@76:   originated the underlying engine.io `Client`. Useful for accessing
rob@76:   request headers such as `Cookie` or `User-Agent`.
rob@76: 
rob@76: ### Socket#id:String
rob@76: 
rob@76:   A unique identifier for the socket session, that comes from the
rob@76:   underlying `Client`.
rob@76: 
rob@76: ### Socket#emit(name:String[, …]):Socket
rob@76: 
rob@76:   Emits an event to the socket identified by the string `name`. Any
rob@76:   other parameters can be included.
rob@76: 
rob@76:   All datastructures are supported, including `Buffer`. JavaScript
rob@76:   functions can't be serialized/deserialized.
rob@76: 
rob@76:   ```js
rob@76:   var io = require('socket.io')();
rob@76:   io.on('connection', function(socket){
rob@76:     socket.emit('an event', { some: 'data' });
rc-web@69:   });
rob@76:   ```
rob@76: 
rob@76: ### Socket#join(name:String[, fn:Function]):Socket
rob@76: 
rob@76:   Adds the socket to the `room`, and fires optionally a callback `fn`
rob@76:   with `err` signature (if any).
rob@76: 
rob@76:   The socket is automatically a member of a room identified with its
rob@76:   session id (see `Socket#id`).
rob@76: 
rob@76:   The mechanics of joining  rooms are handled by the `Adapter`
rob@76:   that has been configured (see `Server#adapter` above), defaulting to
rob@76:   [socket.io-adapter](https://github.com/Automattic/socket.io-adapter).
rob@76: 
rob@76: ### Socket#leave(name:String[, fn:Function]):Socket
rob@76: 
rob@76:   Removes the socket from `room`, and fires optionally a callback `fn`
rob@76:   with `err` signature (if any).
rob@76: 
rob@76:   **Rooms are left automatically upon disconnection**.
rob@76: 
rob@76:   The mechanics of leaving rooms are handled by the `Adapter`
rob@76:   that has been configured (see `Server#adapter` above), defaulting to
rob@76:   [socket.io-adapter](https://github.com/Automattic/socket.io-adapter).
rob@76: 
rob@76: ### Socket#to(room:String):Socket
rob@76: ### Socket#in(room:String):Socket
rob@76: 
rob@76:   Sets a modifier for a subsequent event emission that the event will
rob@76:   only be _broadcasted_ to sockets that have joined the given `room`.
rob@76: 
rob@76:   To emit to multiple rooms, you can call `to` several times.
rob@76: 
rob@76:   ```js
rob@76:   var io = require('socket.io')();
rob@76:   io.on('connection', function(socket){
rob@76:     socket.to('others').emit('an event', { some: 'data' });
rob@76:   });
rob@76:   ```
rob@76: 
rob@76: ### Client
rob@76: 
rob@76:   The `Client` class represents an incoming transport (engine.io)
rob@76:   connection. A `Client` can be associated with many multiplexed `Socket`
rob@76:   that belong to different `Namespace`s.
rob@76: 
rob@76: ### Client#conn
rob@76: 
rob@76:   A reference to the underlying `engine.io` `Socket` connection.
rob@76: 
rob@76: ### Client#request
rob@76: 
rob@76:   A getter proxy that returns the reference to the `request` that
rob@76:   originated the engine.io connection. Useful for accessing
rob@76:   request headers such as `Cookie` or `User-Agent`.
rob@76: 
rob@76: ## Debug / logging
rob@76: 
rob@76: Socket.IO is powered by [debug](http://github.com/visionmedia/debug).
rob@76: In order to see all the debug output, run your app with the environment variable
rob@76: `DEBUG` including the desired scope.
rob@76: 
rob@76: To see the output from all of Socket.IO's debugging scopes you can use:
rob@76: 
rob@76: ```
rob@76: DEBUG=socket.io* node myapp
rc-web@69: ```
rc-web@69: 
rob@76: ## License
rc-web@69: 
rob@76: MIT