Skip to content

Latest commit

 

History

History
343 lines (219 loc) · 9.46 KB

API.md

File metadata and controls

343 lines (219 loc) · 9.46 KB
Raw

Table of Contents

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]) 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.

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]).

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.

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().

socket.send([...args][, ack])

  • args
  • ack (Function)
  • Returns Socket

Sends a message event. See socket.emit(eventName[, ...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.

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.

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.

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.

socket.compress(false).emit('an event', { some: 'data' });

socket.close()

  • Returns Socket

Disconnects the socket manually.

socket.disconnect()

Synonym of socket.close().

Event: 'connect'

Fired upon a connection including a successful reconnection.

Event: 'connect_error'

  • error (Object) error object

Fired upon a connection error.

Event: 'connect_timeout'

Fired upon a connection timeout.

Event: 'error'

  • error (Object) error object

Fired when an error occurs.

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.