PageRenderTime 174ms CodeModel.GetById 81ms app.highlight 12ms RepoModel.GetById 78ms app.codeStats 0ms

/js/lib/Socket.IO-node/support/socket.io-client/README.md

http://github.com/onedayitwillmake/RealtimeMultiplayerNodeJs
Markdown | 262 lines | 156 code | 106 blank | 0 comment | 0 complexity | b6d730bd027b41b4c1f7545dc5df7dba MD5 | raw file
  1socket.io
  2=========
  3
  4#### Sockets for the rest of us
  5
  6The `socket.io` client is basically a simple HTTP Socket interface implementation. It allows you to establish a realtime connection with a server (see `socket.io` server [here](http://github.com/LearnBoost/Socket.IO-node)), hiding the complexity of the different transports (WebSocket, Flash, forever iframe, XHR long polling, XHR multipart encoded, etc), while retaining a WebSocket-like API:
  7
  8	socket = new io.Socket('localhost');
  9	socket.connect();
 10	socket.on('connect', function(){
 11		// connected
 12	});
 13	socket.on('message', function(data){
 14		// data here
 15	});
 16	socket.send('some data');
 17
 18### Features
 19
 20- Supports 
 21	- WebSocket
 22	- Adobe Flash Socket
 23	- ActiveX HTMLFile (IE)
 24	- XHR with multipart encoding
 25	- XHR with long-polling
 26	- JSONP polling (for cross-domain)
 27
 28- Tested on
 29	- Safari 4
 30	- Google Chrome 5
 31	- Internet Explorer 6
 32	- Internet Explorer 7
 33	- Internet Explorer 8
 34	- iPhone Safari
 35	- iPad Safari
 36	- Firefox 3
 37	- Firefox 4 (Minefield)
 38	- Opera 10.61
 39	
 40- ActionScript Socket is known not to work behind proxies, as it doesn't have access to the user agent proxy settings to implement the CONNECT HTTP method. If it fails, `socket.io` will try something else.
 41	
 42- On a successful connection, it remembers the transport for next time (stores it in a cookie).
 43
 44- Small. Closure Compiled with all deps: 5.82kb (gzipped).
 45
 46- Easy to use! See [socket.io-node](http://github.com/LearnBoost/Socket.IO-node) for the server to connect to.
 47
 48### How to use
 49
 50	socket = new io.Socket('localhost');
 51	socket.connect();
 52	socket.send('some data');
 53	socket.on('message', function(data){
 54		alert('got some data' + data);
 55	});
 56	
 57For an example, check out the chat [source](https://github.com/LearnBoost/Socket.IO-node/blob/master/test/chat.html).
 58
 59### Notes
 60
 61If you are serving you .swf from a other domain than socket.io.js you will need to change the WEB_SOCKET_SWF_LOCATION to the insecure version.
 62
 63	<script>WEB_SOCKET_SWF_LOCATION = '/path/to/WebSocketMainInsecure.swf';</script>
 64
 65The insecure version can be found [here](http://github.com/gimite/web-socket-js/blob/master/WebSocketMainInsecure.zip).
 66
 67### Documentation 
 68
 69#### io.Socket
 70
 71	new io.Socket(host, [options]);
 72
 73##### Options:
 74
 75- *secure*
 76
 77		false
 78	
 79	Use secure connections
 80
 81- *port*
 82
 83		Current port or 80
 84	
 85	The port `socket.io` server is attached to (defaults to the document.location port).
 86
 87- *resource*
 88
 89		socket.io
 90
 91  The resource is what allows the `socket.io` server to identify incoming connections by `socket.io` clients. In other words, any HTTP server can implement socket.io and still serve other normal, non-realtime HTTP requests.
 92
 93- *transports*
 94
 95		['websocket', 'flashsocket', 'htmlfile', 'xhr-multipart', 'xhr-polling', 'jsonp-polling']
 96
 97	A list of the transports to attempt to utilize (in order of preference).
 98	
 99- *transportOptions*
100	
101		{
102			someTransport: {
103				someOption: true
104			},
105			...
106		}
107				
108	An object containing (optional) options to pass to each transport.
109
110- *rememberTransport*
111
112		true
113	
114	A boolean indicating if the utilized transport should be remembered in a cookie.
115
116- *connectTimeout*
117
118		5000
119	
120	The amount of miliseconds a transport has to create a connection before we consider it timed out.
121	
122- *tryTransportsOnConnectTimeout*
123
124		true
125
126	A boolean indicating if we should try other transports when the  connectTimeout occurs.
127	
128- *reconnect*
129
130		true
131
132	A boolean indicating if we should automatically reconnect if a connection is disconnected. 
133  
134- *reconnectionDelay*
135
136		500
137
138	The amount of milliseconds before we try to connect to the server again. We are using a exponential back off algorithm for the following reconnections, on each reconnect attempt this value will get multiplied (500 > 1000 > 2000 > 4000 > 8000).
139  
140
141- *maxReconnectionAttempts*
142
143		10
144
145	The amount of attempts should we make using the current transport to connect to the server? After this we will do one final attempt, and re-try with all enabled transport methods before we give up.
146
147##### Properties:
148
149- *options*
150
151	The passed in options combined with the defaults.
152
153- *connected*
154
155	Whether the socket is connected or not.
156	
157- *connecting*
158
159	Whether the socket is connecting or not.
160
161- *reconnecting*
162
163	Whether we are reconnecting or not.
164	
165- *transport*	
166
167	The transport instance.
168
169##### Methods:
170	
171- *connect*
172
173	Establishes a connection.
174	
175- *send(message)*
176	
177	A string of data to send.
178	
179- *disconnect*
180
181	Closes the connection.
182	
183- *on(event, ?)*
184
185	Adds a listener for the event *event*.
186	
187- *removeEvent(event, ?)*
188
189	Removes the listener ? for the event *event*.
190	
191##### Events:
192
193- *connect*
194
195	Fired when the connection is established and the handshake successful.
196	
197- *connecting(transport_type)*
198
199    Fired when a connection is attempted, passing the transport name.
200	
201- *connect_failed*
202
203    Fired when the connection timeout occurs after the last connection attempt.
204	This only fires if the `connectTimeout` option is set.
205	If the `tryTransportsOnConnectTimeout` option is set, this only fires once all
206	possible transports have been tried.
207	
208- *message(message)*
209	
210	Fired when a message arrives from the server
211
212- *close*
213
214	Fired when the connection is closed. Be careful with using this event, as some transports will fire it even under temporary, expected disconnections (such as XHR-Polling).
215	
216- *disconnect*
217
218	Fired when the connection is considered disconnected.
219	
220- *reconnect(transport_type,reconnectionAttempts)*
221
222	Fired when the connection has been re-established. This only fires if the `reconnect` option is set.
223
224- *reconnecting(reconnectionDelay,reconnectionAttempts)*
225
226	Fired when a reconnection is attempted, passing the next delay for the next reconnection.
227
228
229- *reconnect_failed*
230
231	Fired when all reconnection attempts have failed and we where unsucessfull in reconnecting to the server.  
232
233### Contributors
234
235Guillermo Rauch &lt;guillermo@learnboost.com&gt;
236
237Arnout Kazemier &lt;info@3rd-eden.com&gt;
238
239### License 
240
241(The MIT License)
242
243Copyright (c) 2010 LearnBoost &lt;dev@learnboost.com&gt;
244
245Permission is hereby granted, free of charge, to any person obtaining
246a copy of this software and associated documentation files (the
247'Software'), to deal in the Software without restriction, including
248without limitation the rights to use, copy, modify, merge, publish,
249distribute, sublicense, and/or sell copies of the Software, and to
250permit persons to whom the Software is furnished to do so, subject to
251the following conditions:
252
253The above copyright notice and this permission notice shall be
254included in all copies or substantial portions of the Software.
255
256THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
257EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
258MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
259IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
260CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
261TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
262SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.