mirror of
https://github.com/socketio/socket.io.git
synced 2026-04-30 03:00:39 -04:00
[docs] API documentation (#1049)
This commit is contained in:
Damien Arrachequesne
committed by
GitHub
GitHub
parent
177a65fc4a
commit
558163d766
144
README.md
144
README.md
@@ -41,149 +41,7 @@ Socket.IO is compatible with [browserify](http://browserify.org/).
|
||||
|
||||
## 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`
|
||||
See [API](/docs/API.md)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
331
docs/API.md
Normal file
331
docs/API.md
Normal file
@@ -0,0 +1,331 @@
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [IO](#io)
|
||||
- [io.protocol](#ioprotocol)
|
||||
- [io(url[, options])](#iourl-options)
|
||||
- [Class: io.Manager](#manager)
|
||||
- [new Manager(url[, options])](#new-managerurl-options)
|
||||
- [manager.reconnection([value])](#managerreconnectionvalue)
|
||||
- [manager.reconnectionAttempts([value])](#managerreconnectionattemptsvalue)
|
||||
- [manager.reconnectionDelay([value])](#managerreconnectiondelayvalue)
|
||||
- [manager.reconnectionDelayMax([value])](#managerreconnectiondelaymaxvalue)
|
||||
- [manager.timeout([value])](#managertimeoutvalue)
|
||||
- [manager.open([callback])](#manageropencallback)
|
||||
- [manager.connect([callback])](#managerconnectcallback)
|
||||
- [manager.socket(nsp, options)](#managersocketnsp-options)
|
||||
- [Event: 'connect_error'](#event-connect_error)
|
||||
- [Event: 'connect_timeout'](#event-connect_timeout)
|
||||
- [Event: 'reconnect'](#event-reconnect)
|
||||
- [Event: 'reconnect_attempt'](#event-reconnect_attempt)
|
||||
- [Event: 'reconnecting'](#event-reconnecting)
|
||||
- [Event: 'reconnect_error'](#event-reconnect_error)
|
||||
- [Event: 'reconnect_failed'](#event-reconnect_failed)
|
||||
- [Event: 'ping'](#event-ping)
|
||||
- [Event: 'pong'](#event-pong)
|
||||
- [Class: io.Socket](#socket)
|
||||
- [socket.id](#socketid)
|
||||
- [socket.open()](#socketopen)
|
||||
- [socket.connect()](#socketconnect)
|
||||
- [socket.send([...args][, ack])](#socketsendargs-ack)
|
||||
- [socket.emit(eventName[, ...args][, ack])](#socketemiteventname-args-ack)
|
||||
- [socket.on(eventName, callback)](#socketoneventname-callback)
|
||||
- [socket.compress(value)](#socketcompressvalue)
|
||||
- [socket.close()](#socketclose)
|
||||
- [socket.disconnect()](#socketdisconnect)
|
||||
- [Event: 'connect'](#event-connect)
|
||||
- [Event: 'error'](#event-error)
|
||||
- [Event: 'disconnect'](#event-disconnect)
|
||||
- [Event: 'reconnect'](#event-reconnect-1)
|
||||
- [Event: 'reconnect_attempt'](#event-reconnect_attempt-1)
|
||||
- [Event: 'reconnecting'](#event-reconnecting-1)
|
||||
- [Event: 'reconnect_error'](#event-reconnect_error-1)
|
||||
- [Event: 'reconnect_failed'](#event-reconnect_failed-1)
|
||||
|
||||
|
||||
### IO
|
||||
|
||||
Exposed as the `io` namespace in the standalone build, or the result of calling `require('socket.io-client')`.
|
||||
|
||||
#### io.protocol
|
||||
|
||||
* _(Number)_
|
||||
|
||||
The protocol revision number.
|
||||
|
||||
#### io(url[, options])
|
||||
|
||||
- `url` _(String)_
|
||||
- `options` _(Object)_
|
||||
- **Returns** `Socket`
|
||||
|
||||
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`. Passing this option is the equivalent of passing `'force new connection': true` or `forceNew: true`.
|
||||
|
||||
A new `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`.
|
||||
|
||||
See [new Manager(url[, options])](#managerurl-options) for available `options`.
|
||||
|
||||
### Manager
|
||||
|
||||
#### new Manager(url[, options])
|
||||
|
||||
- `url` _(String)_
|
||||
- `options` _(Object)_
|
||||
- `reconnection` _(Boolean)_ whether to reconnect automatically (`true`)
|
||||
- `reconnectionAttempts` _(Number)_ number of reconnection attemps before giving up (`Infinity`)
|
||||
- `reconnectionDelay` _(Number)_ 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` _(Number)_ maximum amount of time to wait between
|
||||
reconnections (`5000`). Each attempt increases the reconnection delay by 2x
|
||||
along with a randomization as above
|
||||
- `randomizationFactor` _(Number)_ (`0.5`), 0 <= randomizationFactor <= 1
|
||||
- `timeout` _(Number)_ connection timeout before a `connect_error`
|
||||
and `connect_timeout` events are emitted (`20000`)
|
||||
- `autoConnect` _(Boolean)_ by setting this false, you have to call `manager.open`
|
||||
whenever you decide it's appropriate
|
||||
- **Returns** `Socket`
|
||||
|
||||
The `options` are also passed to `engine.io-client` upon initialization of the underlying `Socket`. See the available `options` [here](https://github.com/socketio/engine.io-client#methods).
|
||||
|
||||
#### manager.reconnection([value])
|
||||
|
||||
- `value` _(Boolean)_
|
||||
- **Returns** `Manager|Boolean`
|
||||
|
||||
Sets the `reconnection` option, or returns it if no parameters are passed.
|
||||
|
||||
#### manager.reconnectionAttempts([value])
|
||||
|
||||
- `value` _(Number)_
|
||||
- **Returns** `Manager|Number`
|
||||
|
||||
Sets the `reconnectionAttempts` option, or returns it if no parameters are passed.
|
||||
|
||||
#### manager.reconnectionDelay([value])
|
||||
|
||||
- `value` _(Number)_
|
||||
- **Returns** `Manager|Number`
|
||||
|
||||
Sets the `reconnectionDelay` option, or returns it if no parameters are passed.
|
||||
|
||||
#### manager.reconnectionDelayMax([value])
|
||||
|
||||
- `value` _(Number)_
|
||||
- **Returns** `Manager|Number`
|
||||
|
||||
Sets the `reconnectionDelayMax` option, or returns it if no parameters are passed.
|
||||
|
||||
#### manager.timeout([value])
|
||||
|
||||
- `value` _(Number)_
|
||||
- **Returns** `Manager|Number`
|
||||
|
||||
Sets the `timeout` option, or returns it if no parameters are passed.
|
||||
|
||||
#### manager.open([callback])
|
||||
|
||||
- `callback` _(Function)_
|
||||
- **Returns** `Manager`
|
||||
|
||||
If the manager was initiated with `autoConnect` to `false`, launch a new connection attempt.
|
||||
|
||||
The `callback` argument is optional and will be called once the attempt fails/succeeds.
|
||||
|
||||
#### manager.connect([callback])
|
||||
|
||||
Synonym of [manager.open([callback])](#manageropencallback).
|
||||
|
||||
#### manager.socket(nsp, options)
|
||||
|
||||
- `nsp` _(String)_
|
||||
- `options` _(Object)_
|
||||
- **Returns** `Socket`
|
||||
|
||||
Creates a new `Socket` for the given namespace.
|
||||
|
||||
#### Event: 'connect_error'
|
||||
|
||||
- `error` _(Object)_ error object
|
||||
|
||||
Fired upon a connection error.
|
||||
|
||||
#### Event: 'connect_timeout'
|
||||
|
||||
Fired upon a connection timeout.
|
||||
|
||||
#### Event: 'reconnect'
|
||||
|
||||
- `attempt` _(Number)_ reconnection attempt number
|
||||
|
||||
Fired upon a successful reconnection.
|
||||
|
||||
#### Event: 'reconnect_attempt'
|
||||
|
||||
Fired upon an attempt to reconnect.
|
||||
|
||||
#### Event: 'reconnecting'
|
||||
|
||||
- `attempt` _(Number)_ reconnection attempt number
|
||||
|
||||
Fired upon a successful reconnection.
|
||||
|
||||
#### Event: 'reconnect_error'
|
||||
|
||||
- `error` _(Object)_ error object
|
||||
|
||||
Fired upon a reconnection attempt error.
|
||||
|
||||
#### Event: 'reconnect_failed'
|
||||
|
||||
Fired when couldn't reconnect within `reconnectionAttempts`.
|
||||
|
||||
#### Event: 'ping'
|
||||
|
||||
Fired when a ping packet is written out to the server.
|
||||
|
||||
#### Event: 'pong'
|
||||
|
||||
- `ms` _(Number)_ number of ms elapsed since `ping` packet (i.e.: latency).
|
||||
|
||||
Fired when a pong is received from the server.
|
||||
|
||||
### Socket
|
||||
|
||||
#### socket.id
|
||||
|
||||
- _(String)_
|
||||
|
||||
An unique identifier for the socket session. Set after the `connect` event is triggered, and updated after the `reconnect` event.
|
||||
|
||||
```js
|
||||
var socket = io('http://localhost');
|
||||
|
||||
console.log(socket.id); // undefined
|
||||
|
||||
socket.on('connect', function(){
|
||||
console.log(socket.id); // 'G5p5...'
|
||||
});
|
||||
```
|
||||
|
||||
#### socket.open()
|
||||
|
||||
- **Returns** `Socket`
|
||||
|
||||
Opens the socket.
|
||||
|
||||
#### socket.connect()
|
||||
|
||||
Synonym of [socket.open()](#socketopen).
|
||||
|
||||
#### socket.send([...args][, ack])
|
||||
|
||||
- `args`
|
||||
- `ack` _(Function)_
|
||||
- **Returns** `Socket`
|
||||
|
||||
Sends a `message` event. See [socket.emit(eventName[, ...args][, ack])](#socketemiteventname-args-ack).
|
||||
|
||||
#### socket.emit(eventName[, ...args][, ack])
|
||||
|
||||
- `eventName` _(String)_
|
||||
- `args`
|
||||
- `ack` _(Function)_
|
||||
- **Returns** `Socket`
|
||||
|
||||
Emits an event to the socket identified by the string name. Any other parameters can be included. All serializable datastructures are supported, including `Buffer`.
|
||||
|
||||
```js
|
||||
socket.emit('hello', 'world');
|
||||
socket.emit('with-binary', 1, '2', { 3: '4', 5: new Buffer(6) });
|
||||
```
|
||||
|
||||
The `ack` argument is optional and will be called with the server answer.
|
||||
|
||||
```js
|
||||
socket.emit('ferret', 'tobi', function (data) {
|
||||
console.log(data); // data will be 'woot'
|
||||
});
|
||||
|
||||
// server:
|
||||
// io.on('connection', function (socket) {
|
||||
// socket.on('ferret', function (name, fn) {
|
||||
// fn('woot');
|
||||
// });
|
||||
// });
|
||||
```
|
||||
|
||||
#### socket.on(eventName, callback)
|
||||
|
||||
- `eventName` _(String)_
|
||||
- `callback` _(Function)_
|
||||
- **Returns** `Socket`
|
||||
|
||||
Register a new handler for the given event.
|
||||
|
||||
```js
|
||||
socket.on('news', function (data) {
|
||||
console.log(data);
|
||||
});
|
||||
```
|
||||
|
||||
#### socket.compress(value)
|
||||
|
||||
- `value` _(Boolean)_
|
||||
- **Returns** `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' });
|
||||
```
|
||||
|
||||
#### socket.close()
|
||||
|
||||
- **Returns** `Socket`
|
||||
|
||||
Disconnects the socket manually.
|
||||
|
||||
#### socket.disconnect()
|
||||
|
||||
Synonym of [socket.close()](#socketclose).
|
||||
|
||||
#### Event: 'connect'
|
||||
|
||||
Fired upon a connection including a successful reconnection.
|
||||
|
||||
#### Event: 'error'
|
||||
|
||||
- `error` _(Object)_ error object
|
||||
|
||||
Fired upon a connection error.
|
||||
|
||||
#### Event: 'disconnect'
|
||||
|
||||
Fired upon a disconnection.
|
||||
|
||||
#### Event: 'reconnect'
|
||||
|
||||
- `attempt` _(Number)_ reconnection attempt number
|
||||
|
||||
Fired upon a successful reconnection.
|
||||
|
||||
#### Event: 'reconnect_attempt'
|
||||
|
||||
Fired upon an attempt to reconnect.
|
||||
|
||||
#### Event: 'reconnecting'
|
||||
|
||||
- `attempt` _(Number)_ reconnection attempt number
|
||||
|
||||
Fired upon a successful reconnection.
|
||||
|
||||
#### Event: 'reconnect_error'
|
||||
|
||||
- `error` _(Object)_ error object
|
||||
|
||||
Fired upon a reconnection attempt error.
|
||||
|
||||
#### Event: 'reconnect_failed'
|
||||
|
||||
Fired when couldn't reconnect within `reconnectionAttempts`.
|
||||
4
docs/README.md
Normal file
4
docs/README.md
Normal file
@@ -0,0 +1,4 @@
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [API](API.md)
|
||||
Reference in New Issue
Block a user