Connection

Ably::Realtime::Connection Attributes

The Connection object exposes the following public attributes:

id

A unique public identifier String for this connection, used to identify this member in presence events and messages.

state

The current Ably::Realtime::Connection::STATE state of this Connection. See the Connection states for more information.

error_reason

When a connection failure occurs this attribute contains the AblyException.

key

A unique private connection key String used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the recovery_key is used in the recover client options as it contains both the key and the last message serial.

This private connection key can also be used by other REST clients to publish on behalf of this client. See the publishing over REST on behalf of a realtime client documentation for more info.

recovery_key

The recovery key String can be used by another client to recover this connection's state in the recover client options attribute. See connection state recover options for more information.

serial

The serial number Integer of the last message to be received on this connection, used automatically by the library when recovering or resuming a connection. When recovering a connection explicitly, the recovery_key is used in the recover client options as it contains both the key and the last message serial.

Ably::Realtime::Connection Methods

connect

Deferrable connect -> yields Connection

Explicitly calling connect is unnecessary unless the ClientOptions attribute auto_connect is false. Unless already connected or connecting, this method causes the connection to open, entering the connecting state.

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.

close

Deferrable close -> yields Connection

Causes the connection to close, entering the closing state. Once closed, the library will not attempt to re-establish the connection without an explicit call to connect.

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

There are two overloaded versions of this method:

on(ConnectionEvent *event) -> yields ConnectionStateChange

Register the given listener block for the specified ConnectionEvent on the Connection. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the event or state change.

on -> yields ConnectionStateChange

Register the given listener block for all ConnectionEvents on the Connection. The listener is passed a ConnectionStateChange object that contains the current state, previous state, the event, and an optional reason for the event or state change. (For the update event, the current and previous states will be the same).

Parameters

once

There are two overloaded versions of this method:

once(ConnectionEvent *event) -> yields ConnectionStateChange

Register the given listener block for a single occurrence of the specified ConnectionEvent on the Connection. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a ConnectionStateChange object that contains the current state, previous state, the event, and an optional reason for the state change. (For the update event, the current and previous states will be the same).

once -> yields ConnectionStateChange

Register the given listener block for a single occurrence of any ConnectionEvent on the Connection. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the state change. (For the update event, the current and previous states will be the same).

Parameters

off

There are two overloaded versions of this method:

off(ConnectionEvent *event, &block)

Remove the given listener block for the ConnectionEvent.

off(&block)

Remove the given listener block for all ConnectionEvents

Parameters

ping

Deferrable ping -> yields Float seconds

When connected, sends a heartbeat ping to the Ably server and yields the elapsed time in seconds when a heartbeat ping request is echoed from the server. This can be useful for measuring true round-trip latency to the connected Ably server.

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.

Related types

Connection::STATE Enum

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

Connection::EVENT Enum

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

ConnectionStateChange

A Ably::Models::ConnectionStateChange is a type encapsulating state change information emitted by the Connection object. See Connection#on to register a listener for one or more events.

Attributes