Connection

Returns

A Deferrable object is returned from this method.

On successfully connecting to Ably, the registered success blocks for the Deferrable and any block provided to this method yields a Connection object.

Failure to connect will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

Returns

A Deferrable object is returned from this method.

On successfully closing the connection, the registered success blocks for the Deferrable and any block provided to this method yields a Connection object.

Failure to close the connection will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

on(String[] events, listener(ConnectionStateChange stateChange))

Same as above, but registers multiple listeners, one for each event in the array.

If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at error level, so as not to affect other listeners for the same event

If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at error level, so as not to affect other listeners for the same event

off(String[] states, listener)

Removes the given listener from all ConnectionEvents in the array.

off(String state)

Removes all listeners for a given @[email protected]

off(String[] states)

Removes all listeners for all ConnectionEvents in the array.

off()

Removes all listeners (including both those registered against specific events and those registered without an event).

Returns

A Deferrable object is returned from this method.

On successfully echoing a heartbeat from Ably, the registered success blocks for the Deferrable and any block provided to this method yields a Float representing the time in seconds for the heartbeat ping request to be echoed.

Failure to receive a heartbeat ping will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

A io.ably.lib.realtime.CompletionListener is an interface allowing a client to be notified of the outcome of an asynchronous operation.

public interface CompletionListener {
  // Called when the associated operation completes successfully,
  public void onSuccess();

  // Called when the associated operation completes with an error.
  public void onError(ErrorInfo reason);
}

ConnectionState is a String with a value matching any of the Realtime Connection states.

var ConnectionStates = [
  'initialized',
  'connecting',
  'connected',
  'disconnected',
  'suspended',
  'closing',
  'closed',
  'failed'
]

io.ably.lib.realtime.ConnectionState is an enum representing all the Realtime Connection states.

public enum ConnectionState {
  initialized,   // 0
  connecting,    // 1
  connected,     // 2
  disconnected,  // 3
  suspended,     // 4
  closing,       // 5
  closed,        // 6
  failed         // 7
}

IO.Ably.Realtime.ConnectionState is an enum representing all the Realtime Connection states.

public enum ConnectionState
{
    Initialized,    //0
    Connecting,     //1
    Connected,      //2
    Disconnected,   //3
    Suspended,      //4
    Closing,        //5
    Closed,         //6
    Failed          //7
};

Ably::Realtime::Connection::STATE is an enum-like value representing all the Realtime Connection states. STATE can be represented interchangeably as either symbols or constants.

Symbol states

:initialized # =>  0
:connecting # =>   1
:connected # =>    2
:disconnected # => 3
:suspended # =>    4
:closing # =>      5
:closed # =>       6
:failed # =>       7

Constant states

Connection::STATE.Initialized # =>  0
Connection::STATE.Connecting # =>   1
Connection::STATE.Connected # =>    2
Connection::STATE.Disconnected # => 3
Connection::STATE.Suspended # =>    4
Connection::STATE.Closing # =>      5
Connection::STATE.Closed # =>       6
Connection::STATE.Failed # =>       7

Example usage

# Example with symbols
client.connection.on(:connected) { ... }

# Example with constants
client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... }

# Interchangeable
Ably::Realtime::Connection::STATE.Connected == :connected # => true

ARTRealtimeConnectionState is an enum representing all the Realtime Connection states.

typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionState) {
    ARTRealtimeInitialized,
    ARTRealtimeConnecting,
    ARTRealtimeConnected,
    ARTRealtimeDisconnected,
    ARTRealtimeSuspended,
    ARTRealtimeClosing,
    ARTRealtimeClosed,
    ARTRealtimeFailed
};

public enum ARTRealtimeConnectionState : UInt {
    case Initialized
    case Connecting
    case Connected
    case Disconnected
    case Suspended
    case Closing
    case Closed
    case Failed
}

ConnectionState is an enum representing all the Realtime Connection states.

const (
  StateConnInitialized = 1
  StateConnConnecting = 2
  StateConnConnected = 4
  StateConnDisconnected = 8
  StateConnSuspended = 16
  StateConnClosing = 32
  StateConnClosed = 64
  StateConnFailed = 128
)

ConnectionEvent is a String that can be emitted as an event on the Connection object; either a Realtime Connection state or an update event.

var ConnectionEvents = [
  'initialized',
  'connecting',
  'connected',
  'disconnected',
  'suspended',
  'closing',
  'closed',
  'failed',
  'update'
]

io.ably.lib.realtime.ConnectionEvent is an enum representing all the events that can be emitted be the Connection; either a Realtime Connection state or an update event.

public enum ConnectionEvent {
  initialized,   // 0
  connecting,    // 1
  connected,     // 2
  disconnected,  // 3
  suspended,     // 4
  closing,       // 5
  closed,        // 6
  failed,        // 7
  update         // 8
}

IO.Ably.Realtime.ConnectionEvent is an enum representing all the events that can be emitted be the Connection; either a Realtime Connection state or an Update event.

public enum ConnectionState
{
    Initialized,    //0
    Connecting,     //1
    Connected,      //2
    Disconnected,   //3
    Suspended,      //4
    Closing,        //5
    Closed,         //6
    Failed,         //7
    update          //8
};

Ably::Realtime::Connection::EVENT is an enum-like value representing all the events that can be emitted be the Connection; either a Realtime Connection state or an :update event. EVENT can be represented interchangeably as either symbols or constants.

Symbol states

:initialized # =>  0
:connecting # =>   1
:connected # =>    2
:disconnected # => 3
:suspended # =>    4
:closing # =>      5
:closed # =>       6
:failed # =>       7
:update # =>       8

Constant states

Connection::EVENT.Initialized # =>  0
Connection::EVENT.Connecting # =>   1
Connection::EVENT.Connected # =>    2
Connection::EVENT.Disconnected # => 3
Connection::EVENT.Suspended # =>    4
Connection::EVENT.Closing # =>      5
Connection::EVENT.Closed # =>       6
Connection::EVENT.Failed # =>       7
Connection::EVENT.Update # =>       8

Example usage

# Example with symbols
client.connection.on(:connected) { ... }

# Example with constants
client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... }

# Interchangeable
Ably::Realtime::Connection::STATE.Connected == :connected # => true

ARTRealtimeConnectionEvent is an enum representing all the events that can be emitted be the Connection; either a Realtime Connection state or an Update event.

typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionEvent) {
    ARTRealtimeConnectionEventInitialized,
    ARTRealtimeConnectionEventConnecting,
    ARTRealtimeConnectionEventConnected,
    ARTRealtimeConnectionEventDisconnected,
    ARTRealtimeConnectionEventSuspended,
    ARTRealtimeConnectionEventClosing,
    ARTRealtimeConnectionEventClosed,
    ARTRealtimeConnectionEventFailed,
    ARTRealtimeConnectionEventUpdate
};

public enum ARTRealtimeConnectionEvent : UInt {
    case Initialized
    case Connecting
    case Connected
    case Disconnected
    case Suspended
    case Closing
    case Closed
    case Failed
    case Update
}

ConnectionEvent is a String that can be emitted as an event on the Connection object; either a Realtime Connection state or an update event.

const (
  StateConnInitialized = 1
  StateConnConnecting = 2
  StateConnConnected = 4
  StateConnDisconnected = 8
  StateConnSuspended = 16
  StateConnClosing = 32
  StateConnClosed = 64
  StateConnFailed = 128
)

A io.ably.lib.realtime.ConnectionStateListener is an interface allowing a client to be notified of connection state change. See Connection#on to register a listener for one or more events.

public interface ConnectionStateListener {
  // Called when the connection state changes
  public void onConnectionStateChanged(ConnectionStateListener.ConnectionStateChange state);
}

A LastConnectionDetails object provides details on the last connection in a browser environment persisted when the window beforeunload fired. This object is provided to the callback specified in the recover attribute of ClientOptions. The callback in turn instructs the client library whether the connection should be recovered or not. See connection state recovery for more information.

Please note that as sessionStorage is used to persist the LastConnectionDetails between page reloads, it is only available for pages in the same origin and top-level browsing context.

Properties

recoveryKey

An opaque string obtained from the recoveryKey attribute of the Connection object before the page was unloaded. This property is used by the library to recover the connection
Type: String

disconnectedAt

the time at which the previous library was abruptly disconnected before the page was unloaded. This is represented as milliseconds since epoch
Type: Integer

location

a clone of location object of the previous page’s document object before the page was unloaded. A common use case for this attribute is to ensure that the previous page URL is the same as the current URL before allowing the connection to be recovered. For example, you may want the connection to be recovered only for page reloads, but not when a user navigates to a different page
Type: String

clientId

the clientId of the client’s Auth object before the page was unloaded. A common use case for this attribute is to ensure that the current logged in user’s clientId matches the previous connection’s clientId before allowing the connection to be recovered. Ably prohibits changing a clientId for an existing connection, so any mismatch in clientId during a recover will result in the connection moving to the failed state
Type: String