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