1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
# socket.io-client
[](http://travis-ci.org/socketio/socket.io-client)
[](https://david-dm.org/socketio/socket.io-client)
[](https://david-dm.org/socketio/socket.io-client#info=devDependencies)
[](http://slack.socket.io)
## How to use
A standalone build of `socket.io-client` is exposed automatically by the
socket.io server as `/socket.io/socket.io.js`. Alternatively you can
serve the file `socket.io.js` found at the root of this repository.
```html
<script src="/socket.io/socket.io.js"></script>
<script>
var socket = io('http://localhost');
socket.on('connect', function(){});
socket.on('event', function(data){});
socket.on('disconnect', function(){});
</script>
```
Socket.IO is compatible with [browserify](http://browserify.org/).
### Node.JS (server-side usage)
Add `socket.io-client` to your `package.json` and then:
```js
var socket = require('socket.io-client')('http://localhost');
socket.on('connect', function(){});
socket.on('event', function(data){});
socket.on('disconnect', function(){});
```
## API
### IO(url:String, opts:Object):Socket
Exposed as the `io` namespace in the standalone build, or the result
of calling `require('socket.io-client')`.
When called, it creates a new `Manager` for the given URL, and attempts
to reuse an existing `Manager` for subsequent calls, unless the
`multiplex` option is passed with `false`.
The rest of the options are passed to the `Manager` constructor (see below
for details).
A `Socket` instance is returned for the namespace specified by the
pathname in the URL, defaulting to `/`. For example, if the `url` is
`http://localhost/users`, a transport connection will be established to
`http://localhost` and a Socket.IO connection will be established to
`/users`.
### IO#protocol
Socket.io protocol revision number this client works with.
### IO#Socket
Reference to the `Socket` constructor.
### IO#Manager
Reference to the `Manager` constructor.
### IO#Emitter
Reference to the `Emitter` constructor.
### Manager(url:String, opts:Object)
A `Manager` represents a connection to a given Socket.IO server. One or
more `Socket` instances are associated with the manager. The manager
can be accessed through the `io` property of each `Socket` instance.
The `opts` are also passed to `engine.io` upon initialization of the
underlying `Socket`.
Options:
- `reconnection` whether to reconnect automatically (`true`)
- `reconnectionAttempts` (`Infinity`) before giving up
- `reconnectionDelay` how long to initially wait before attempting a new
reconnection (`1000`). Affected by +/- `randomizationFactor`,
for example the default initial delay will be between 500 to 1500ms.
- `reconnectionDelayMax` maximum amount of time to wait between
reconnections (`5000`). Each attempt increases the reconnection delay by 2x
along with a randomization as above
- `randomizationFactor` (`0.5`), 0 <= randomizationFactor <= 1
- `timeout` connection timeout before a `connect_error`
and `connect_timeout` events are emitted (`20000`)
- `autoConnect` by setting this false, you have to call `manager.open`
whenever you decide it's appropriate
#### Events
- `connect_error`. Fired upon a connection error.
Parameters:
- `Object` error object
- `connect_timeout`. Fired upon a connection timeout.
- `reconnect`. Fired upon a successful reconnection.
Parameters:
- `Number` reconnection attempt number
- `reconnect_attempt`. Fired upon an attempt to reconnect.
- `reconnecting`. Fired upon an attempt to reconnect.
Parameters:
- `Number` reconnection attempt number
- `reconnect_error`. Fired upon a reconnection attempt error.
Parameters:
- `Object` error object
- `reconnect_failed`. Fired when couldn't reconnect within `reconnectionAttempts`
- `ping`. Fired when a ping packet is written out to the server.
- `pong`. Fired when a pong is received from the server.
Parameters:
- `Number` number of ms elapsed since `ping` packet (i.e.: latency).
The events above are also emitted on the individual sockets that
reconnect that depend on this `Manager`.
### Manager#reconnection(v:Boolean):Manager
Sets the `reconnection` option, or returns it if no parameters
are passed.
### Manager#reconnectionAttempts(v:Boolean):Manager
Sets the `reconnectionAttempts` option, or returns it if no parameters
are passed.
### Manager#reconnectionDelay(v:Boolean):Manager
Sets the `reconectionDelay` option, or returns it if no parameters
are passed.
### Manager#reconnectionDelayMax(v:Boolean):Manager
Sets the `reconectionDelayMax` option, or returns it if no parameters
are passed.
### Manager#timeout(v:Boolean):Manager
Sets the `timeout` option, or returns it if no parameters
are passed.
### Socket
#### Socket#id:String
A property on the `socket` instance that is equal to the underlying engine.io socket id.
The property is present once the socket has connected, is removed when the socket disconnects and is updated if the socket reconnects.
#### 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
socket.compress(false).emit('an event', { some: 'data' });
```
#### Events
- `connect`. Fired upon a connection including a successful reconnection.
- `error`. Fired upon a connection error
Parameters:
- `Object` error data
- `disconnect`. Fired upon a disconnection.
- `reconnect`. Fired upon a successful reconnection.
Parameters:
- `Number` reconnection attempt number
- `reconnect_attempt`. Fired upon an attempt to reconnect.
- `reconnecting`. Fired upon an attempt to reconnect.
Parameters:
- `Number` reconnection attempt number
- `reconnect_error`. Fired upon a reconnection attempt error.
Parameters:
- `Object` error object
- `reconnect_failed`. Fired when couldn't reconnect within `reconnectionAttempts`
## License
[MIT](/LICENSE)
|
