PageRenderTime 85ms CodeModel.GetById 61ms app.highlight 20ms RepoModel.GetById 1ms app.codeStats 0ms

/js/lib/Socket.IO-node/README.md

http://github.com/onedayitwillmake/RealtimeMultiplayerNodeJs
Markdown | 229 lines | 135 code | 94 blank | 0 comment | 0 complexity | 0cc5056b2062608942fa88c728b77a14 MD5 | raw file
  1Socket.IO Server: Sockets for the rest of us
  2============================================
  3
  4The `Socket.IO` server provides seamless support for a variety of transports intended for realtime communication.
  5
  6- WebSocket 
  7- WebSocket over Flash (+ XML security policy support)
  8- XHR Polling
  9- XHR Multipart Streaming
 10- Forever Iframe
 11- JSONP Polling (for cross domain)
 12
 13## Requirements
 14
 15- Node v0.1.103+ with `crypto` module support (make sure you have OpenSSL
 16  headers when installing Node to get it)
 17- The [Socket.IO client](http://github.com/LearnBoost/Socket.IO), to connect from the browser
 18
 19## How to use
 20
 21To run the demo, execute the following:
 22
 23	git clone git://github.com/LearnBoost/Socket.IO-node.git socket.io
 24	cd socket.io/example/
 25	sudo node server.js
 26
 27and point your browser to `http://localhost:8080`. In addition to `8080`, if the transport `flashsocket` is enabled, a server will be initialized to listen for requests on port `843`.
 28
 29### Implementing it on your project
 30
 31`Socket.IO` is designed not to take over an entire port or Node `http.Server` instance. This means that if you choose to have your HTTP server listen on port `80`, `socket.io` can intercept requests directed to it, and normal requests will still be served.
 32
 33By default, the server will intercept requests that contain `socket.io` in the path / resource part of the URI. You can change this as shown in the available options below.
 34
 35On the server:
 36
 37	var http = require('http'), 
 38			io = require('./path/to/socket.io'),
 39			
 40	server = http.createServer(function(req, res){
 41		// your normal server code
 42		res.writeHead(200, {'Content-Type': 'text/html'});
 43		res.end('<h1>Hello world</h1>');
 44	});
 45	
 46	server.listen(80);
 47			
 48	// socket.io, I choose you
 49	var socket = io.listen(server);
 50	
 51	socket.on('connection', function(client){
 52	  // new client is here!
 53	  client.on('message', function(){ … })
 54	  client.on('disconnect', function(){ … })
 55	});
 56	
 57On the client:
 58
 59	<script src="/socket.io/socket.io.js"></script>
 60	<script>
 61		var socket = new io.Socket();
 62		socket.connect();
 63		socket.on('connect', function(){ … })
 64		socket.on('message', function(){ … })
 65		socket.on('disconnect', function(){ … })
 66	</script>
 67
 68The [client-side](http://github.com/learnboost/socket.io) files are served automatically by `Socket.IO-node`.
 69
 70## Documentation
 71
 72### Listener
 73
 74	io.listen(<http.Server>, [options])
 75	
 76Returns: a `Listener` instance
 77	
 78Public Properties:
 79
 80- *server*
 81
 82	An instance of _process.http.Server_.
 83	
 84- *options*
 85
 86	The passed-in options, combined with the defaults.
 87	
 88- *clients*
 89	
 90	An object of clients, indexed by session ID.
 91	
 92Methods:
 93
 94- *addListener(event, ?)*
 95
 96	Adds a listener for the specified event. Optionally, you can pass it as an option to `io.listen`, prefixed by `on`. For example: `onClientConnect: function(){}`
 97	
 98- *removeListener(event, ?)*	
 99
100	Removes a listener from the listener array for the specified event.
101	
102- *broadcast(message, [except])*
103
104	Broadcasts a message to all clients. Optionally, you can pass a single session ID or array of session IDs to avoid broadcasting to, as the second argument.
105	
106Options:
107	
108- *resource*
109
110		socket.io
111
112  The resource is what allows the `socket.io` server to identify incoming connections from `socket.io` clients. Make sure they're in sync.
113  
114- *flashPolicyServer*
115
116		true
117		
118	Create a Flash Policy file server on port `843` (this is restricted port and you will need to have root permission). If you disable the FlashPolicy file server, Socket.IO will automatically fall back to serving the policy file inline.
119		
120
121- *transports*
122
123		['websocket', 'flashsocket', 'htmlfile', 'xhr-multipart', 'xhr-polling',
124    'jsonp-polling']
125		
126	A list of the accepted transports.
127	
128- *transportOptions*
129	
130	An object of options to pass to each transport. For example `{ websocket: { closeTimeout: 8000 }}`
131	
132- *log*
133	
134		ƒ(){ sys.log }
135		
136	The logging function. Defaults to outputting to `stdout` through `sys.log`
137
138Events:
139	
140- *clientConnect(client)*
141	
142	Fired when a client is connected. Receives the Client instance as parameter.
143	
144- *clientMessage(message, client)*
145
146	Fired when a message from a client is received. Receives the message and Client instance as parameters.
147	
148- *clientDisconnect(client)*
149
150	Fired when a client is disconnected. Receives the Client instance as a parameter.
151
152Important note: `this` in the event listener refers to the `Listener` instance.
153
154### Client
155	
156	Client(listener, req, res)
157	
158Public Properties:
159
160- *listener*
161
162	The `Listener` instance to which this client belongs.
163
164- *connected*
165
166	Whether the client is connected.
167	
168- *connections*
169
170	Number of times the client has connected.
171	
172Methods:
173
174- *send(message)*
175
176	Sends a message to the client.
177	
178- *broadcast(message)*
179
180	Sends a message to all other clients. Equivalent to Listener::broadcast(message, client.sessionId).
181
182## Protocol
183
184One of the design goals is that you should be able to implement whatever protocol you desire without `Socket.IO` getting in the way. `Socket.IO` has a minimal, unobtrusive protocol layer, consisting of two parts:
185
186* Connection handshake
187	
188	This is required to simulate a full duplex socket with transports such as XHR Polling or Server-sent Events (which is a "one-way socket"). The basic idea is that the first message received from the server will be a JSON object that contains a session ID used for further communications exchanged between the client and server. 
189	
190	The concept of session also naturally benefits a full-duplex WebSocket, in the event of an accidental disconnection and a quick reconnection. Messages that the server intends to deliver to the client are cached temporarily until reconnection.
191	
192	The implementation of reconnection logic (potentially with retries) is left for the user. By default, transports that are keep-alive or open all the time (like WebSocket) have a timeout of 0 if a disconnection is detected.
193	
194* Message batching
195
196	Messages are buffered in order to optimize resources. In the event of the server trying to send multiple messages while a client is temporarily disconnected (eg: xhr polling), the messages are stacked and then encoded in a lightweight way, and sent to the client whenever it becomes available.
197
198Despite this extra layer, the messages are delivered unaltered to the various event listeners. You can `JSON.stringify()` objects, send XML, or even plain text.
199
200## Credits
201
202- Guillermo Rauch &lt;guillermo@learnboost.com&gt; ([Guille](http://github.com/guille))
203
204- Arnout Kazemier ([3rd-Eden](http://github.com/3rd-Eden))
205
206## License 
207
208(The MIT License)
209
210Copyright (c) 2010 LearnBoost &lt;dev@learnboost.com&gt;
211
212Permission is hereby granted, free of charge, to any person obtaining
213a copy of this software and associated documentation files (the
214'Software'), to deal in the Software without restriction, including
215without limitation the rights to use, copy, modify, merge, publish,
216distribute, sublicense, and/or sell copies of the Software, and to
217permit persons to whom the Software is furnished to do so, subject to
218the following conditions:
219
220The above copyright notice and this permission notice shall be
221included in all copies or substantial portions of the Software.
222
223THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
224EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
225MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
226IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
227CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
228TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
229SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.