# Connection

## <If lang="javascript,nodejs,flutter">Connection Properties</If><If lang="swift,objc">ARTConnection Properties</If><If lang="ruby">Ably::Realtime::Connection Attributes</If><If lang="java">io.ably.lib.realtime.Connection Members</If><If lang="csharp">IO.Ably.Realtime.Connection Properties</If> 

The `Connection` object exposes the following public <If lang="javascript,nodejs,flutter,objc,swift,csharp">properties</If><If lang="ruby">attributes</If><If lang="java">members</If>:

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">id</If><If lang="csharp">Id</If> 

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

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">state</If><If lang="csharp">State</If> 

The current <If lang="java">[`io.ably.lib.realtime.ConnectionState`](#connection-state) `state`</If><If lang="csharp">[`IO.Ably.Realtime.ConnectionState`](#connection-state) `state`</If><If lang="ruby">[`Ably::Realtime::Connection::STATE`](#connection-state) `state`</If><If lang="objc,swift">[`ARTRealtimeConnectionState`](#connection-state) `state`</If><If lang="javascript,nodejs,flutter">`state String`</If> of this Connection. See the [`Connection` states](https://ably.com/docs/connect/states.md#connection-states) for more information.

### <If lang="javascript,nodejs,flutter,objc,swift">errorReason</If><If lang="java">reason</If><If lang="csharp">ErrorReason</If><If lang="ruby">error_reason</If> 

When a connection failure occurs this <If lang="flutter,objc,swift,ruby">attribute</If><If lang="java">member</If><If lang="javascript,nodejs,csharp">property</If> contains the <If lang="javascript,nodejs,csharp">[`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info)</If><If lang="java,ruby">[`AblyException`](https://ably.com/docs/api/realtime-sdk/types.md#ably-exception)</If>.

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">key</If><If lang="csharp">Key</If> 

A unique private connection key `String` used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the <If lang="javascript,nodejs,flutter,java,objc,swift,csharp">`recoveryKey`</If><If lang="ruby">`recovery_key`</If> is used in the `recover` [client options](https://ably.com/docs/api/realtime-sdk.md#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](https://ably.com/docs/pub-sub/advanced.md#publish-on-behalf) for more info.

<If lang="flutter,csharp,java,objc,ruby,swift">

### <If lang="flutter,java,objc,swift">recoveryKey</If><If lang="ruby">recovery_key</If><If lang="csharp">RecoveryKey</If> 

The recovery key `String` can be used by another client to recover this connection's state in the <If lang="flutter,java,objc,ruby,swift">`recover`</If><If lang="csharp">`Recover`</If> [client options](https://ably.com/docs/api/realtime-sdk.md#client-options) <If lang="flutter,objc,swift,csharp">property</If><If lang="java">member</If><If lang="ruby">attribute</If>. See [connection state recover options](https://ably.com/docs/connect/states.md#connection-state-recover-options) for more information.

### <If lang="flutter,java,objc,ruby,swift">serial</If><If lang="csharp">Serial</If> 

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 <If lang="flutter,java,objc,swift">`recoveryKey`</If><If lang="ruby">`recovery_key`</If><If lang="csharp">`RecoveryKey`</If> is used in the <If lang="flutter,java,objc,ruby,swift">`recover`</If><If lang="csharp">`Recover`</If> [client options](https://ably.com/docs/api/realtime-sdk.md#client-options) as it contains both the `key` and the last message `serial`.

</If>

## <If lang="javascript,nodejs,flutter">Connection Methods</If><If lang="swift,objc">ARTConnection Methods</If><If lang="ruby">Ably::Realtime::Connection Methods</If><If lang="java">io.ably.lib.realtime.Connection Methods</If><If lang="csharp">IO.Ably.Realtime.Connection Methods</If> 

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">connect</If><If lang="csharp">Connect</If> 

<If lang="javascript,nodejs,objc,swift">

`connect(): void`

</If>
<If lang="ruby">

`Deferrable connect -> yields Connection`

</If>
<If lang="java">

`void connect()`

</If>
<If lang="csharp">

`void Connect()`

</If>
<If lang="flutter">

`Future<void> connect()`

</If>

Explicitly calling <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">`connect`</If><If lang="csharp">`Connect`</If> is unnecessary unless the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types.md#client-options) attribute <If lang="javascript,nodejs,flutter,java,objc,swift">`autoConnect`</If><If lang="ruby">`auto_connect`</If><If lang="csharp">`AutoConnect`</If> is `false`. Unless already `connected` or `connecting`, this method causes the connection to open, entering the `connecting` state.

<If lang="ruby">

#### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from this method.

On successfully connecting to Ably, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to this method yields a [`Connection`](https://ably.com/docs/api/realtime-sdk/connection.md) object.

Failure to connect will trigger the errback callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](#error-info) object containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api.md#common) documentation.

</If>

<If lang="flutter">

#### Returns

`Future<void>`

Failure to connect will throw an `AblyException` with an [`errorInfo`](#error-info) property containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api.md#common) documentation.

</If>

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">close</If><If lang="csharp">Close</If> 

<If lang="javascript,nodejs,objc,swift">

`close(): void`

</If>
<If lang="ruby">

`Deferrable close -> yields Connection`

</If>
<If lang="java">

`void close()`

</If>
<If lang="csharp">

`void Close()`

</If>
<If lang="flutter">

`Future<void> close()`

</If>

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 <If lang="javascript,nodejs,flutter,java,objc,swift">[`connect()`](#connect)</If><If lang="csharp">[`Connect()`](#connect)</If><If lang="ruby">[`connect`](#connect)</If>.

<If lang="ruby">

#### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from this method.

On successfully closing the connection, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) and any block provided to this method yields a [`Connection`](https://ably.com/docs/api/realtime-sdk/connection.md) object.

Failure to close the connection will trigger the errback callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](#error-info) object containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api.md#common) documentation.

</If>

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">on</If><If lang="csharp">On</If> 

There are <If lang="javascript,nodejs">three</If><If lang="flutter,java,objc,swift,ruby,csharp">two</If> overloaded versions of this method:

<If lang="javascript,nodejs">

`on(String event, listener(ConnectionStateChange stateChange))`

</If>
<If lang="ruby">

`on(ConnectionEvent *event) -> yields ConnectionStateChange`

</If>
<If lang="java">

`void on(ConnectionEvent event, ConnectionStateListener listener)`

</If>
<If lang="objc,swift">

`on(event: ARTRealtimeConnectionEvent, call: (ARTConnectionStateChange?) -> Void) -> ARTEventListener`

</If>
<If lang="csharp">

`void On(ConnectionEvent event, Action<ConnectionStateChange> action)`

</If>
<If lang="flutter">

`Stream<ably.ConnectionStateChange> on(ably.ConnectionStateChange stateChange)`

</If>

<If lang="flutter">
The Stream returned can be subscribed for with a listener.

`final streamSubscription = stream.listen(listener)`

</If>

Register the given listener <If lang="ruby">block</If><If lang="swift,objc">function</If><If lang="csharp">action</If><If lang="javascript,nodejs,flutter,java">listener</If> for the specified [`ConnectionEvent`](#connection-event) on the `Connection`. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, and an optional reason for the event or state change.

<If lang="javascript,nodejs">
`on(String[] events, listener(ConnectionStateChange stateChange))`

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

<If lang="javascript,nodejs">

`on(listener(ConnectionStateChange stateChange))`

</If>
<If lang="ruby">

`on -> yields ConnectionStateChange`

</If>
<If lang="java">

`void on(ConnectionStateListener listener)`

</If>
<If lang="objc,swift">

`on(call: (ARTConnectionStateChange?) -> Void) -> ARTEventListener`

</If>
<If lang="csharp">

`void On(Action<ConnectionStateChange> action)`

</If>
<If lang="flutter">

`Stream<ably.ConnectionStateChange> on()`

</If>

<If lang="flutter">
The Stream returned can be subscribed for with a listener.

`final streamSubscription = stream.listen(listener)`

</If>

Register the given listener <If lang="ruby">block</If><If lang="swift,objc">function</If><If lang="csharp">action</If><If lang="javascript,nodejs,flutter,java">listener</If> for all [ConnectionEvents](#connection-event) on the `Connection`. The listener is passed a [ConnectionStateChange](#connection-state-change) 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).

<If lang="javascript,nodejs">
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>

#### Parameters

<If lang="flutter">

| Parameter | Description | Type |
|-----------|-------------|------|
| event | the connection event to subscribe to | [`ConnectionEvent`](#connection-event) |

</If>
<If lang="javascript,nodejs,java,csharp,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">event(s)</If><If lang="java,csharp,ruby,swift,objc">event</If> | <If lang="javascript,nodejs">the connection event(s) to subscribe to</If><If lang="java,csharp,swift,objc">the connection event to subscribe to</If><If lang="ruby">the connection event as a Symbol such as `:connected` or `ConnectionEvent` object to subscribe to</If> | <If lang="javascript,nodejs">`String` or `String[]`</If><If lang="java,csharp">[`ConnectionEvent`](#connection-event)</If><If lang="ruby">[`ConnectionEvent`](#connection-event)</If><If lang="swift,objc">[`ARTRealtimeConnectionEvent`](#connection-event)</If> |
| <If lang="javascript,nodejs">listener</If><If lang="java">listener</If><If lang="csharp">action</If><If lang="ruby">&block</If><If lang="swift,objc">call</If> | <If lang="javascript,nodejs">is a function of the form `function(stateChange)` to be notified for matching events</If><If lang="java">listener to be notified for matching events</If><If lang="csharp">action to be executed for matching events</If><If lang="ruby">listener block that is yielded to for matching events</If><If lang="swift,objc">called with matching events</If> | <If lang="javascript,nodejs">function</If><If lang="java">[`ConnectionStateListener`](#connection-state-listener)</If><If lang="csharp">[`ConnectionStateChange`](#connection-state-listener)</If><If lang="ruby">block</If><If lang="swift,objc">function</If> |

</If>

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">once</If><If lang="csharp">Once</If> 

There are two overloaded versions of this method:

<If lang="javascript,nodejs,flutter">

`once(String event, listener(ConnectionStateChange stateChange))`

</If>
<If lang="ruby">

`once(ConnectionEvent *event) -> yields ConnectionStateChange`

</If>
<If lang="java">

`void once(ConnectionEvent event, ConnectionStateListener listener)`

</If>
<If lang="objc,swift">

`once(event: ARTRealtimeConnectionEvent, call: (ARTConnectionStateChange?) -> Void) -> ARTEventListener`

</If>
<If lang="csharp">

`void Once(ConnectionEvent event, Action<ConnectionStateChange> action)`

</If>

Register the given listener <If lang="ruby">block</If><If lang="swift,objc">function</If><If lang="csharp">action</If><If lang="javascript,nodejs,flutter,java">listener</If> for a single occurrence of the specified [ConnectionEvent](#connection-event) 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](#connection-state-change) 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).

<If lang="javascript,nodejs,flutter">

`once(listener(ConnectionStateChange stateChange))`

</If>
<If lang="ruby">

`once -> yields ConnectionStateChange`

</If>
<If lang="java">

`void once(ConnectionStateListener listener)`

</If>
<If lang="objc,swift">

`once(call: (ARTConnectionStateChange?) -> Void) -> ARTEventListener`

</If>
<If lang="csharp">

`void Once(Action<ConnectionStateChange> action)`

</If>

Register the given listener <If lang="ruby">block</If><If lang="csharp">action</If><If lang="javascript,nodejs,flutter,java,objc,swift">listener</If> for a single occurrence of any [ConnectionEvent](#connection-event) 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](#connection-state-change) 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).

<If lang="javascript,nodejs">
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>

#### Parameters

<If lang="javascript,nodejs,java,csharp,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">event(s)</If><If lang="java,csharp,ruby,swift,objc">event</If> | <If lang="javascript,nodejs">the connection event(s) to subscribe to</If><If lang="java,csharp,swift,objc">the connection event to subscribe to</If><If lang="ruby">the connection event as a Symbol such as `:connected` or `ConnectionEvent` object to subscribe to</If> | <If lang="javascript,nodejs">`String` or `String[]`</If><If lang="java,csharp">[`ConnectionEvent`](#connection-event)</If><If lang="ruby">[`ConnectionEvent`](#connection-event)</If><If lang="swift,objc">[`ARTRealtimeConnectionEvent`](#connection-event)</If> |
| <If lang="javascript,nodejs">listener</If><If lang="java">listener</If><If lang="csharp">action</If><If lang="ruby">&block</If><If lang="swift,objc">call</If> | <If lang="javascript,nodejs">is a function of the form `function(stateChange)` to be notified for a single occurrence of a matching event</If><If lang="java">listener to be notified for a single occurrence of a matching state change</If><If lang="csharp">action to be executed for matching state changes</If><If lang="ruby">listener block that is yielded to for a single occurrence of a matching event</If><If lang="swift,objc">called with matching events</If> | <If lang="javascript,nodejs">function</If><If lang="java">[`ConnectionStateListener`](#connection-state-listener)</If><If lang="csharp">[`ConnectionStateChange`](#connection-state-listener)</If><If lang="ruby">block</If><If lang="swift,objc">function</If> |

</If>

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">off</If><If lang="csharp">Off</If> 

There are <If lang="javascript,nodejs">six</If><If lang="flutter,java,objc,swift,ruby,csharp">two</If> overloaded versions of this method:

<If lang="javascript,nodejs,flutter">

`off(String event, listener)`

</If>
<If lang="ruby">

`off(ConnectionEvent *event, &block)`

</If>
<If lang="java">

`void off(ConnectionEvent event, ConnectionStateListener listener)`

</If>
<If lang="objc,swift">

`off(event: ARTRealtimeConnectionEvent, listener: ARTEventListener)`

</If>
<If lang="csharp">

`void Off(ConnectionEvent event, Action<ConnectionStateChange> action)`

</If>

Remove the given listener <If lang="ruby">block</If><If lang="csharp">action</If><If lang="javascript,nodejs,flutter,java,objc,swift">listener</If> for the [ConnectionEvent](#connection-event).

<If lang="javascript,nodejs,flutter">

`off(listener)`

</If>
<If lang="ruby">

`off(&block)`

</If>
<If lang="java">

`void off(ConnectionStateListener listener)`

</If>
<If lang="objc,swift">

`off(listener: ARTEventListener)`

</If>
<If lang="csharp">

`void Off(Action<ConnectionStateChange> action)`

</If>

Remove the given listener <If lang="ruby">block</If><If lang="csharp">action</If><If lang="javascript,nodejs,flutter,java,objc,swift">listener</If> for all [ConnectionEvents](#connection-event)

<If lang="javascript,nodejs">
`off(String[] states, listener)`

Removes the given listener from all [ConnectionEvents](#connection-event) in the array.

`off(String state)`

Removes all listeners for a given [`ConnectionEvent`s.](#connection-event)

`off(String[] states)`

Removes all listeners for all [ConnectionEvents](#connection-event) in the array.

`off()`

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

</If>

#### Parameters

<If lang="javascript,nodejs,java,csharp,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">event(s)</If><If lang="java,csharp,ruby,swift,objc">event</If> | <If lang="javascript,nodejs">the connection event(s) to unsubscribe from</If><If lang="java,swift,objc">the connection event to unsubscribe from</If><If lang="csharp">the connection event to subscribe to</If><If lang="ruby">the connection event as a Symbol such as `:connected` or `ConnectionEvent` object to unsubscribe from</If> | <If lang="javascript,nodejs">`String` or `String[]`</If><If lang="java,csharp">[`ConnectionEvent`](#connection-event)</If><If lang="ruby">[`ConnectionEvent`](#connection-event)</If><If lang="swift,objc">[`ARTRealtimeConnectionEvent`](#connection-event)</If> |
| <If lang="javascript,nodejs,java,swift,objc">listener</If><If lang="csharp">action</If><If lang="ruby">&block</If> | <If lang="javascript,nodejs">is the listener function to be removed</If><If lang="java">is the listener to be removed</If><If lang="csharp">action to be executed for matching event changes</If><If lang="ruby">is the listener block to be removed</If><If lang="swift,objc">previous return value from a `on` or `once` call</If> | <If lang="javascript,nodejs">function</If><If lang="java">[`ConnectionStateListener`](#connection-state-listener)</If><If lang="csharp">[`ConnectioneventChangeEventArgs`](#connection-state-listener)</If><If lang="ruby">block</If><If lang="swift,objc">ARTEventListener</If> |

</If>

<If lang="flutter">
`streamSubscription` obtained from calling `on` can be used to cancel a listener by calling `streamSubscription.cancel`.
</If>

### <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">ping</If><If lang="csharp">Ping</If> 

<If lang="flutter">

`ping(callback(ErrorInfo err, Number responseInMilliseconds))`

</If>
<If lang="javascript,nodejs">

`ping(): Promise<Number>`

</If>
<If lang="ruby">

`Deferrable ping -> yields Float seconds`

</If>
<If lang="java">

`void ping(CompletionListener listener)`

</If>
<If lang="objc,swift">

`ping(callback: (ARTErrorInfo?) -> Void)`

</If>
<If lang="csharp">

`void Ping(Action<TimeSpan?, ErrorInfo> callback)`

</If>

When connected, sends a heartbeat ping to the Ably server and <If lang="javascript,nodejs">executes the callback with any error and the response time in milliseconds</If><If lang="flutter,objc,swift,csharp">executes the callback</If><If lang="java">calls the listener</If><If lang="ruby">yields the elapsed time in seconds</If> 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.

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise resolves with a number representing the time in seconds for the heartbeat ping request to be echoed. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

<If lang="ruby">

#### Returns

A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) object is returned from this method.

On successfully echoing a heartbeat from Ably, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types.md#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`](https://ably.com/docs/api/realtime-sdk/types.md#deferrable) with an [`ErrorInfo`](#error-info) object containing an error response as defined in the [Ably REST API](https://ably.com/docs/api/rest-api.md#common) documentation.

</If>

<If lang="javascript,nodejs">

### listeners 

`listeners(eventName?): null | connectionEventCallback[]`

Returns the listeners for the specified [`ConnectionEvent`](#connection-event).

</If>

<If lang="javascript,nodejs">

### whenState 

`whenState(targetState): Promise<null | ConnectionStateChange>`

If the connection is already in a given state, returns a promise which immediately resolves to `null`. Otherwise calls [`once`](#once) to return a promise which resolves the next time the connection transitions to the given state.

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| targetState | The [`ConnectionState`](#connection-state) to wait for | `ConnectionState` |

#### Returns

Returns a promise. If the connection is already in the given state, the promise will immediately resolve to `null`. If not, it will call [`once()`](#once) to return a promise which resolves the next time the connection transitions to the given state.

</If>

<If lang="javascript,nodejs">

### createRecoveryKey 

`createRecoveryKey(): null | string`

Generates a string that can be used by another client to recover the current connection's state using the `recover` property of the [`ClientOptions`](https://ably.com/docs/api/realtime-sdk/types.md#client-options) object. See [connection state recover options](https://ably.com/connect/states#connection-state-recover-options) for more information.

</If>

## Related types 

<If lang="java">

### io.ably.lib.realtime.CompletionListener 

A <If lang="java">`io.ably.lib.realtime.CompletionListener`</If> is an interface allowing a client to be notified of the outcome of an asynchronous operation.

<Code>
```java
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);
}
```
</Code>

</If>

### <If lang="javascript,nodejs">ConnectionState</If><If lang="swift,objc">ARTRealtimeConnectionState</If><If lang="ruby">Connection::STATE Enum</If><If lang="java">io.ably.lib.realtime.ConnectionState Enum</If><If lang="csharp">IO.Ably.Realtime.ConnectionState Enum</If><If lang="flutter">ably.ConnectionState Enum</If> 

<If lang="javascript,nodejs">

`ConnectionState` is a String with a value matching any of the [`Realtime Connection` states](https://ably.com/docs/connect/states.md).

<Code>
```javascript
var ConnectionStates = [
  'initialized',
  'connecting',
  'connected',
  'disconnected',
  'suspended',
  'closing',
  'closed',
  'failed'
]
```
</Code>

</If>

<If lang="java">

`io.ably.lib.realtime.ConnectionState` is an enum representing all the [`Realtime Connection` states](https://ably.com/docs/connect/states.md).

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

</If>

<If lang="csharp">

`IO.Ably.Realtime.ConnectionState` is an enum representing all the [`Realtime Connection` states](https://ably.com/docs/connect/states.md).

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

</If>

<If lang="ruby">

`Ably::Realtime::Connection::STATE` is an enum-like value representing all the [`Realtime Connection` states](https://ably.com/docs/connect/states.md). `STATE` can be represented interchangeably as either symbols or constants.

#### Symbol states

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

#### Constant states

<Code>
```ruby
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
```
</Code>

#### Example usage

<Code>
```ruby
# 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
```
</Code>

</If>

<If lang="objc,swift">

`ARTRealtimeConnectionState` is an enum representing all the [`Realtime Connection` states](https://ably.com/docs/connect/states.md).

<If lang="objc">
<Code>
```objc
typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionState) {
    ARTRealtimeInitialized,
    ARTRealtimeConnecting,
    ARTRealtimeConnected,
    ARTRealtimeDisconnected,
    ARTRealtimeSuspended,
    ARTRealtimeClosing,
    ARTRealtimeClosed,
    ARTRealtimeFailed
};
```
</Code>
</If>

<If lang="swift">
<Code>
```swift
public enum ARTRealtimeConnectionState : UInt {
    case Initialized
    case Connecting
    case Connected
    case Disconnected
    case Suspended
    case Closing
    case Closed
    case Failed
}
```
</Code>
</If>

</If>

<If lang="flutter">

`ably.ConnectionState` is an enum representing all the [`Realtime Connection` states](https://ably.com/docs/connect/states.md).

<Code>
```flutter
enum ConnectionState {
  initialized,
  connecting,
  connected,
  disconnected,
  suspended,
  closing,
  closed,
  failed
}
```
</Code>

</If>

### <If lang="javascript,nodejs">ConnectionEvent</If><If lang="swift,objc">ARTRealtimeConnectionEvent</If><If lang="ruby">Connection::EVENT Enum</If><If lang="java">io.ably.lib.realtime.ConnectionEvent Enum</If><If lang="csharp">IO.Ably.Realtime.ConnectionEvent Enum</If><If lang="flutter">ably.ConnectionEvent Enum</If> 

<If lang="javascript,nodejs">

`ConnectionEvent` is a String that can be emitted as an event on the `Connection` object; either a [`Realtime Connection` state](https://ably.com/docs/connect/states.md) or an `update` event.

<Code>
```javascript
var ConnectionEvents = [
  'initialized',
  'connecting',
  'connected',
  'disconnected',
  'suspended',
  'closing',
  'closed',
  'failed',
  'update'
]
```
</Code>

</If>

<If lang="java">

`io.ably.lib.realtime.ConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [`Realtime Connection` state](https://ably.com/docs/connect/states.md) or an `update` event.

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

</If>

<If lang="csharp">

`IO.Ably.Realtime.ConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [`Realtime Connection` state](https://ably.com/docs/connect/states.md) or an `Update` event.

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

</If>

<If lang="ruby">

`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](https://ably.com/docs/connect/states.md) or an `:update` event. `EVENT` can be represented interchangeably as either symbols or constants.

#### Symbol states

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

#### Constant states

<Code>
```ruby
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
```
</Code>

#### Example usage

<Code>
```ruby
# 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
```
</Code>

</If>

<If lang="objc,swift">

`ARTRealtimeConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [`Realtime Connection` state](https://ably.com/docs/connect/states.md) or an `Update` event.

<If lang="objc">
<Code>
```objc
typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionEvent) {
    ARTRealtimeConnectionEventInitialized,
    ARTRealtimeConnectionEventConnecting,
    ARTRealtimeConnectionEventConnected,
    ARTRealtimeConnectionEventDisconnected,
    ARTRealtimeConnectionEventSuspended,
    ARTRealtimeConnectionEventClosing,
    ARTRealtimeConnectionEventClosed,
    ARTRealtimeConnectionEventFailed,
    ARTRealtimeConnectionEventUpdate
};
```
</Code>
</If>

<If lang="swift">
<Code>
```swift
public enum ARTRealtimeConnectionEvent : UInt {
    case Initialized
    case Connecting
    case Connected
    case Disconnected
    case Suspended
    case Closing
    case Closed
    case Failed
    case Update
}
```
</Code>
</If>

</If>

<If lang="flutter">

`ably.ConnectionEvent` is an enum representing all the events that can be emitted be the `Connection`; either a [`Realtime Connection` state](https://ably.com/docs/connect/states.md) or an `update` event.

<Code>
```flutter
enum ConnectionEvent {
  initialized,
  connecting,
  connected,
  disconnected,
  suspended,
  closing,
  closed,
  failed,
  update
}
```
</Code>

</If>

### <If lang="java">io.ably.lib.realtime.ConnectionStateListener</If> 

<If lang="java">

A <If lang="java">`io.ably.lib.realtime.ConnectionStateListener`</If> is an interface allowing a client to be notified of connection state change. See [`Connection#on`](https://ably.com/docs/api/realtime-sdk/connection.md#on) to register a listener for one or more events.

<Code>
```java
public interface ConnectionStateListener {
  // Called when the connection state changes
  public void onConnectionStateChanged(ConnectionStateListener.ConnectionStateChange state);
}
```
</Code>

</If>

### <If lang="javascript,nodejs">ConnectionStateChange Object</If><If lang="objc,swift">ARTConnectionStateChange</If><If lang="java">io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange</If><If lang="ruby">ConnectionStateChange</If><If lang="csharp">IO.Ably.Realtime.ConnectionStateChange</If><If lang="flutter">ably.ConnectionStateChange</If> 

A <If lang="java">`io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange`</If><If lang="ruby">`Ably::Models::ConnectionStateChange`</If><If lang="swift,objc">`ARTConnectionStateChange`</If><If lang="csharp">`IO.Ably.Realtime.ConnectionStateChange`</If><If lang="javascript,nodejs,flutter">`ConnectionStateChange`</If> is a type encapsulating state change information emitted by the [`Connection`](https://ably.com/docs/api/realtime-sdk/connection.md) object. See [`Connection#on`](https://ably.com/docs/api/realtime-sdk/connection.md#on) to register a listener for one or more events.

#### <If lang="javascript,nodejs,flutter,objc,swift,csharp">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

| Property | Description | Type |
|----------|-------------|------|
| <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">current</If><If lang="csharp">Current</If> | the new state | <If lang="javascript,nodejs,flutter,objc,swift">[State `String`](https://ably.com/docs/api/realtime-sdk/types.md#connection-state)</If><If lang="ruby">[`Connection::STATE`](https://ably.com/docs/api/realtime-sdk/types.md#connection-state)</If><If lang="java,csharp">[`ConnectionState`](https://ably.com/docs/api/realtime-sdk/types.md#connection-state)</If> |
| <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">previous</If><If lang="csharp">Previous</If> | the previous state. (for the `update` event, this will be equal to the `current` state) | <If lang="javascript,nodejs,flutter,objc,swift">[State `String`](https://ably.com/docs/api/realtime-sdk/types.md#connection-state)</If><If lang="ruby">[`Connection::STATE`](https://ably.com/docs/api/realtime-sdk/types.md#connection-state)</If><If lang="java,csharp">[`ConnectionState`](https://ably.com/docs/api/realtime-sdk/types.md#connection-state)</If> |
| <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">event</If><If lang="csharp">Event</If> | the event that triggered this state change | [<If lang="javascript,nodejs,flutter,java,objc,swift,csharp">`ConnectionEvent`</If><If lang="ruby">Connection::EVENT</If>](https://ably.com/docs/api/realtime-sdk/types.md#connection-event) |
| <If lang="javascript,nodejs,flutter,java,objc,ruby,swift">reason</If><If lang="csharp">Reason</If> | an [`ErrorInfo`](#error-info) containing any information relating to the transition | [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) |
| <If lang="javascript,nodejs,flutter,java,objc,swift">retryIn</If><If lang="ruby">retry_in</If><If lang="csharp">RetryIn</If> | Duration upon which the library will retry a connection where applicable, as <If lang="javascript,nodejs,flutter,java,objc,swift">milliseconds</If><If lang="ruby">seconds</If><If lang="csharp">a `Timespan`</If> | <If lang="javascript,nodejs,flutter,objc,ruby,swift">`Integer`</If><If lang="csharp">`Timespan`</If><If lang="java">`Long Integer`</If> |

### <If lang="javascript">LastConnectionDetails</If> 

<If lang="javascript">

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`](https://ably.com/docs/api/realtime-sdk/types.md#client-options). The callback in turn instructs the client library whether the connection should be recovered or not. See [connection state recovery](https://ably.com/docs/connect/states.md) for more information.

Please note that as [`sessionStorage`](https://www.w3.org/TR/webstorage/) 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

| Property | Description | Type |
|----------|-------------|------|
| recoveryKey | An opaque string obtained from the [recoveryKey](https://ably.com/docs/api/realtime-sdk/connection.md#recovery-key) attribute of the [Connection object](https://ably.com/docs/api/realtime-sdk/connection.md) before the page was unloaded. This property is used by the library to recover the connection | `String` |
| disconnectedAt | the time at which the previous library was abruptly disconnected before the page was unloaded. This is represented as milliseconds since epoch | `Integer` |
| location | a clone of [`location`](https://www.w3.org/TR/html5/browsers.html#the-location-interface) 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 | `String` |
| clientId | the [`clientId`](https://ably.com/docs/api/realtime-sdk/authentication.md#client-id) of the [client's Auth object](https://ably.com/docs/api/realtime-sdk/authentication.md) 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 | `String` |

</If>