vnfmarket/src/main/webapp/vnfmarket/node_modules/socket.io/Readme.md

   1 # Socket.IO
   2
   3 Socket.IO is a Node.JS project that makes WebSockets and realtime possible in
   4 all browsers. It also enhances WebSockets by providing built-in multiplexing,
   5 horizontal scalability, automatic JSON encoding/decoding, and more.
   6
   7 ## How to Install
   8
   9 ```bash
  10 npm install socket.io
  11 ```
  12
  13 ## How to use
  14
  15 First, require `socket.io`:
  16
  17 ```js
  18 var io = require('socket.io');
  19 ```
  20
  21 Next, attach it to a HTTP/HTTPS server. If you're using the fantastic `express`
  22 web framework:
  23
  24 #### Express 3.x
  25
  26 ```js
  27 var app = express()
  28   , server = require('http').createServer(app)
  29   , io = io.listen(server);
  30
  31 server.listen(80);
  32
  33 io.sockets.on('connection', function (socket) {
  34   socket.emit('news', { hello: 'world' });
  35   socket.on('my other event', function (data) {
  36     console.log(data);
  37   });
  38 });
  39 ```
  40
  41 #### Express 2.x
  42
  43 ```js
  44 var app = express.createServer()
  45   , io = io.listen(app);
  46
  47 app.listen(80);
  48
  49 io.sockets.on('connection', function (socket) {
  50   socket.emit('news', { hello: 'world' });
  51   socket.on('my other event', function (data) {
  52     console.log(data);
  53   });
  54 });
  55 ```
  56
  57 Finally, load it from the client side code:
  58
  59 ```html
  60 <script src="/socket.io/socket.io.js"></script>
  61 <script>
  62   var socket = io.connect('http://localhost');
  63   socket.on('news', function (data) {
  64     console.log(data);
  65     socket.emit('my other event', { my: 'data' });
  66   });
  67 </script>
  68 ```
  69
  70 For more thorough examples, look at the `examples/` directory.
  71
  72 ## Short recipes
  73
  74 ### Sending and receiving events.
  75
  76 Socket.IO allows you to emit and receive custom events.
  77 Besides `connect`, `message` and `disconnect`, you can emit custom events:
  78
  79 ```js
  80 // note, io.listen(<port>) will create a http server for you
  81 var io = require('socket.io').listen(80);
  82
  83 io.sockets.on('connection', function (socket) {
  84   io.sockets.emit('this', { will: 'be received by everyone' });
  85
  86   socket.on('private message', function (from, msg) {
  87     console.log('I received a private message by ', from, ' saying ', msg);
  88   });
  89
  90   socket.on('disconnect', function () {
  91     io.sockets.emit('user disconnected');
  92   });
  93 });
  94 ```
  95
  96 ### Storing data associated to a client
  97
  98 Sometimes it's necessary to store data associated with a client that's
  99 necessary for the duration of the session.
 100
 101 #### Server side
 102
 103 ```js
 104 var io = require('socket.io').listen(80);
 105
 106 io.sockets.on('connection', function (socket) {
 107   socket.on('set nickname', function (name) {
 108     socket.set('nickname', name, function () { socket.emit('ready'); });
 109   });
 110
 111   socket.on('msg', function () {
 112     socket.get('nickname', function (err, name) {
 113       console.log('Chat message by ', name);
 114     });
 115   });
 116 });
 117 ```
 118
 119 #### Client side
 120
 121 ```html
 122 <script>
 123   var socket = io.connect('http://localhost');
 124
 125   socket.on('connect', function () {
 126     socket.emit('set nickname', prompt('What is your nickname?'));
 127     socket.on('ready', function () {
 128       console.log('Connected !');
 129       socket.emit('msg', prompt('What is your message?'));
 130     });
 131   });
 132 </script>
 133 ```
 134
 135 ### Restricting yourself to a namespace
 136
 137 If you have control over all the messages and events emitted for a particular
 138 application, using the default `/` namespace works.
 139
 140 If you want to leverage 3rd-party code, or produce code to share with others,
 141 socket.io provides a way of namespacing a `socket`.
 142
 143 This has the benefit of `multiplexing` a single connection. Instead of
 144 socket.io using two `WebSocket` connections, it'll use one.
 145
 146 The following example defines a socket that listens on '/chat' and one for
 147 '/news':
 148
 149 #### Server side
 150
 151 ```js
 152 var io = require('socket.io').listen(80);
 153
 154 var chat = io
 155   .of('/chat')
 156   .on('connection', function (socket) {
 157     socket.emit('a message', { that: 'only', '/chat': 'will get' });
 158     chat.emit('a message', { everyone: 'in', '/chat': 'will get' });
 159   });
 160
 161 var news = io
 162   .of('/news');
 163   .on('connection', function (socket) {
 164     socket.emit('item', { news: 'item' });
 165   });
 166 ```
 167
 168 #### Client side:
 169
 170 ```html
 171 <script>
 172   var chat = io.connect('http://localhost/chat')
 173     , news = io.connect('http://localhost/news');
 174
 175   chat.on('connect', function () {
 176     chat.emit('hi!');
 177   });
 178
 179   news.on('news', function () {
 180     news.emit('woot');
 181   });
 182 </script>
 183 ```
 184
 185 ### Sending volatile messages.
 186
 187 Sometimes certain messages can be dropped. Let's say you have an app that
 188 shows realtime tweets for the keyword `bieber`.
 189
 190 If a certain client is not ready to receive messages (because of network slowness
 191 or other issues, or because he's connected through long polling and is in the
 192 middle of a request-response cycle), if he doesn't receive ALL the tweets related
 193 to bieber your application won't suffer.
 194
 195 In that case, you might want to send those messages as volatile messages.
 196
 197 #### Server side
 198
 199 ```js
 200 var io = require('socket.io').listen(80);
 201
 202 io.sockets.on('connection', function (socket) {
 203   var tweets = setInterval(function () {
 204     getBieberTweet(function (tweet) {
 205       socket.volatile.emit('bieber tweet', tweet);
 206     });
 207   }, 100);
 208
 209   socket.on('disconnect', function () {
 210     clearInterval(tweets);
 211   });
 212 });
 213 ```
 214
 215 #### Client side
 216
 217 In the client side, messages are received the same way whether they're volatile
 218 or not.
 219
 220 ### Getting acknowledgements
 221
 222 Sometimes, you might want to get a callback when the client confirmed the message
 223 reception.
 224
 225 To do this, simply pass a function as the last parameter of `.send` or `.emit`.
 226 What's more, when you use `.emit`, the acknowledgement is done by you, which
 227 means you can also pass data along:
 228
 229 #### Server side
 230
 231 ```js
 232 var io = require('socket.io').listen(80);
 233
 234 io.sockets.on('connection', function (socket) {
 235   socket.on('ferret', function (name, fn) {
 236     fn('woot');
 237   });
 238 });
 239 ```
 240
 241 #### Client side
 242
 243 ```html
 244 <script>
 245   var socket = io.connect(); // TIP: .connect with no args does auto-discovery
 246   socket.on('connect', function () { // TIP: you can avoid listening on `connect` and listen on events directly too!
 247     socket.emit('ferret', 'tobi', function (data) {
 248       console.log(data); // data will be 'woot'
 249     });
 250   });
 251 </script>
 252 ```
 253
 254 ### Broadcasting messages
 255
 256 To broadcast, simply add a `broadcast` flag to `emit` and `send` method calls.
 257 Broadcasting means sending a message to everyone else except for the socket
 258 that starts it.
 259
 260 #### Server side
 261
 262 ```js
 263 var io = require('socket.io').listen(80);
 264
 265 io.sockets.on('connection', function (socket) {
 266   socket.broadcast.emit('user connected');
 267   socket.broadcast.json.send({ a: 'message' });
 268 });
 269 ```
 270
 271 ### Rooms
 272
 273 Sometimes you want to put certain sockets in the same room, so that it's easy
 274 to broadcast to all of them together.
 275
 276 Think of this as built-in channels for sockets. Sockets `join` and `leave`
 277 rooms in each socket.
 278
 279 #### Server side
 280
 281 ```js
 282 var io = require('socket.io').listen(80);
 283
 284 io.sockets.on('connection', function (socket) {
 285   socket.join('justin bieber fans');
 286   socket.broadcast.to('justin bieber fans').emit('new fan');
 287   io.sockets.in('rammstein fans').emit('new non-fan');
 288 });
 289 ```
 290
 291 ### Using it just as a cross-browser WebSocket
 292
 293 If you just want the WebSocket semantics, you can do that too.
 294 Simply leverage `send` and listen on the `message` event:
 295
 296 #### Server side
 297
 298 ```js
 299 var io = require('socket.io').listen(80);
 300
 301 io.sockets.on('connection', function (socket) {
 302   socket.on('message', function () { });
 303   socket.on('disconnect', function () { });
 304 });
 305 ```
 306
 307 #### Client side
 308
 309 ```html
 310 <script>
 311   var socket = io.connect('http://localhost/');
 312   socket.on('connect', function () {
 313     socket.send('hi');
 314
 315     socket.on('message', function (msg) {
 316       // my msg
 317     });
 318   });
 319 </script>
 320 ```
 321
 322 ### Changing configuration
 323
 324 Configuration in socket.io is TJ-style:
 325
 326 #### Server side
 327
 328 ```js
 329 var io = require('socket.io').listen(80);
 330
 331 io.configure(function () {
 332   io.set('transports', ['websocket', 'flashsocket', 'xhr-polling']);
 333 });
 334
 335 io.configure('development', function () {
 336   io.set('transports', ['websocket', 'xhr-polling']);
 337   io.enable('log');
 338 });
 339 ```
 340
 341 ## License
 342
 343 (The MIT License)
 344
 345 Copyright (c) 2011 Guillermo Rauch &lt;guillermo@learnboost.com&gt;
 346
 347 Permission is hereby granted, free of charge, to any person obtaining
 348 a copy of this software and associated documentation files (the
 349 'Software'), to deal in the Software without restriction, including
 350 without limitation the rights to use, copy, modify, merge, publish,
 351 distribute, sublicense, and/or sell copies of the Software, and to
 352 permit persons to whom the Software is furnished to do so, subject to
 353 the following conditions:
 354
 355 The above copyright notice and this permission notice shall be
 356 included in all copies or substantial portions of the Software.
 357
 358 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
 359 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 360 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 361 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 362 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 363 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 364 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.