From 64d9ccb6ae21a12d6fbd61b371397d8d5f2e783f Mon Sep 17 00:00:00 2001 From: nanalelfe Date: Sat, 23 Jul 2016 23:10:00 -0400 Subject: need pull --- node_modules/socket.io/Readme.md | 427 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 427 insertions(+) create mode 100644 node_modules/socket.io/Readme.md (limited to 'node_modules/socket.io/Readme.md') diff --git a/node_modules/socket.io/Readme.md b/node_modules/socket.io/Readme.md new file mode 100644 index 0000000..74e2e89 --- /dev/null +++ b/node_modules/socket.io/Readme.md @@ -0,0 +1,427 @@ + +# socket.io + +[![Build Status](https://secure.travis-ci.org/socketio/socket.io.svg)](https://travis-ci.org/socketio/socket.io) +[![Dependency Status](https://david-dm.org/socketio/socket.io.svg)](https://david-dm.org/socketio/socket.io) +[![devDependency Status](https://david-dm.org/socketio/socket.io/dev-status.svg)](https://david-dm.org/socketio/socket.io#info=devDependencies) +![NPM version](https://badge.fury.io/js/socket.io.svg) +![Downloads](https://img.shields.io/npm/dm/socket.io.svg?style=flat) +[![](http://slack.socket.io/badge.svg?)](http://slack.socket.io) + +## How to use + +The following example attaches socket.io to a plain Node.JS +HTTP server listening on port `3000`. + +```js +var server = require('http').createServer(); +var io = require('socket.io')(server); +io.on('connection', function(socket){ + socket.on('event', function(data){}); + socket.on('disconnect', function(){}); +}); +server.listen(3000); +``` + +### Standalone + +```js +var io = require('socket.io')(); +io.on('connection', function(socket){}); +io.listen(3000); +``` + +### 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 = require('express')(); +var server = require('http').createServer(app); +var io = require('socket.io')(server); +io.on('connection', function(){ /* … */ }); +server.listen(3000); +``` + +### In conjunction with Koa + +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').createServer(app.callback()); +var io = require('socket.io')(server); +io.on('connection', function(){ /* … */ }); +server.listen(3000); +``` + +## API + +### Server + + Exposed by `require('socket.io')`. + +### Server() + + Creates a new `Server`. Works with and without `new`: + + ```js + var io = require('socket.io')(); + // or + var Server = require('socket.io'); + var io = new Server(); + ``` + +### 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/socketio/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/socketio/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#origins(v:Function):Server + + Sets the allowed origins as dynamic function. Function takes two arguments `origin:String` and `callback(error, success)`, where `success` is a boolean value indicating whether origin is allowed or not. + + __Potential drawbacks__: + * in some situations, when it is not possible to determine `origin` it may have value of `*` + * As this function will be executed for every request, it is advised to make this function work as fast as possible + * If `socket.io` is used together with `Express`, the CORS headers will be affected only for `socket.io` requests. For Express can use [cors](https://github.com/expressjs/cors) + + +### 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#close + + Closes socket server + + ```js + var Server = require('socket.io'); + var PORT = 3030; + var server = require('http').Server(); + + var io = Server(PORT); + + io.close(); // Close current server + + server.listen(PORT); // PORT is free to use + + io = Server(server); + ``` + +### 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 + + Hash of `Socket` objects that are connected to this namespace indexed + by `id`. + +### Namespace#clients(fn:Function) + + Gets a list of client IDs connected to this namespace (across all nodes if applicable). + + An example to get all clients in a namespace: + + ```js + var io = require('socket.io')(); + io.of('/chat').clients(function(error, clients){ + if (error) throw error; + console.log(clients); // => [PZDoMHjiu8PYfRiKAAAF, Anw2LatarvGVVXEIAAAD] + }); + ``` + + An example to get all clients in namespace's room: + + ```js + var io = require('socket.io')(); + io.of('/chat').in('general').clients(function(error, clients){ + if (error) throw error; + console.log(clients); // => [Anw2LatarvGVVXEIAAAD] + }); + ``` + + As with broadcasting, the default is all clients from the default namespace ('/'): + + ```js + var io = require('socket.io')(); + io.clients(function(error, clients){ + if (error) throw error; + console.log(clients); // => [6em3d4TJP8Et9EMNAAAA, G5p55dHhGgUnLUctAAAB] + }); + ``` + +### 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')); + }); + ``` + + 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:Object + + A hash of strings identifying the rooms this socket is in, indexed by + room name. + +### Socket#client:Client + + A reference to the underlying `Client` object. + +### Socket#conn:Socket + + A reference to the underlying `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/socketio/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/socketio/socket.io-adapter). + +### Socket#to(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' }); + }); + ``` + +### Socket#in(room:String):Socket + + Same as `Socket#to` + +### Socket#compress(v:Boolean):Socket + + Sets a modifier for a subsequent event emission that the event data will + only be _compressed_ if the value is `true`. Defaults to `true` when you don't call the method. + + ```js + var io = require('socket.io')(); + io.on('connection', function(socket){ + socket.compress(false).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](https://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 +``` + +## License + +MIT -- cgit v1.2.3