Skip to main content

Connection Establishment

After completing the necessary configuration, it's time to establish an initial connection to the XMPP server.

Connecting to the server with Whixp is straightforward. You only need to call one method to make the connection. The connect() method initiates the connection process, which includes DNS SRV lookup (if no host is specified), socket establishment, stream negotiation, authentication, and feature processing.

final whixp = Whixp(
    jabberID: 'vsevolod@localhost',
    password: 'passwd',
    internalDatabasePath: 'initial',
    logger: Log(enableWarning: true),
  );

  whixp.connect();

If you check the logs, you will see the "Finished processing stream features." message, which indicates that the connection was successful and that further processing will take place:

[Whixp] SEND: <iq type="set" id="51ec9-2113-8b29-44fbca57"><bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/></iq>
[Whixp] RECEIVED: <iq type='result' id='51ec9-2113-8b29-44fbca57' xmlns="jabber:client"><bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'><jid>vsevex@localhost/179773712250924621162146</jid></bind></iq>
[Whixp] SEND: <enable resume="true" xmlns="urn:xmpp:sm:3"/>
[Whixp] RECEIVED: <enabled resume='true' max='30' id='g2gCbQAAABgxNzk3NzM3MTIyNTA5MjQ2MjExNjIxNDZtAAAACKNXIdgVg21Z' xmlns='urn:xmpp:sm:3'/>
[Whixp] Starting Ping keep alive...
[Whixp] Finished processing stream features.

Reconnection policy​

You can configure the Whixp instance to automatically reconnect in case of any errors. This can be achieved by providing a reconnection policy; however, the built-in options are limited. You can either develop your own reconnection policy or use the RandomBackoffReconnectionPolicy class. You need to specify the minimum and maximum backoff times, from which a random value will be selected for reconnection attempts.

final whixp = Whixp(
    jabberID: 'vsevolod@localhost',
    password: 'passwd',
    internalDatabasePath: 'whixp',
    reconnectionPolicy: RandomBackoffReconnectionPolicy(0, 1),
  );

    whixp.connect();

When there is an error with connection, the Whixp debug output will be similar to this:

[Whixp] Resetting reconnection policy
[Whixp] Trying to connect to localhost on port 5222
[Whixp] Failure occurred. Starting random backoff with 5s
[Whixp] Timer elapsed. Waiting for lock...
[Whixp] Reconnecting...

Connection States​

Whixp provides several connection states that you can monitor through event handlers. The main states are:

  • TransportState.connecting: The client is attempting to establish a connection to the server.
  • TransportState.connected: The socket connection has been successfully established.
  • TransportState.disconnected: The connection has been closed or terminated.
  • TransportState.connectionFailure: A connection attempt has failed.
  • TransportState.reconnecting: The client is attempting to reconnect after a disconnection.

You can listen to these state changes using the state event handler:

whixp.addEventHandler<TransportState>('state', (state) {
  switch (state) {
    case TransportState.connecting:
      print('Connecting to server...');
      break;
    case TransportState.connected:
      print('Connected successfully!');
      break;
    case TransportState.disconnected:
      print('Disconnected from server');
      break;
    case TransportState.connectionFailure:
      print('Connection failed');
      break;
    case TransportState.reconnecting:
      print('Reconnecting...');
      break;
  }
});

Disconnecting​

To gracefully disconnect from the XMPP server, you can call the disconnect() method:

await whixp.disconnect();

This method will:

  • Send an unavailable presence (if configured)
  • Close the XML stream properly
  • Clean up resources
  • End the session

Connection Timeout​

You can configure the connection timeout when creating a Whixp instance. The default timeout is 2000 milliseconds (2 seconds). This timeout determines how long the client will wait when establishing the initial socket connection:

final whixp = Whixp(
  jabberID: 'vsevolod@localhost',
  password: 'passwd',
  internalDatabasePath: 'whixp',
  connectionTimeout: 5000, // 5 seconds
);

Keep-Alive (Ping)​

Whixp supports automatic keep-alive functionality to maintain the connection and detect network issues. When enabled, the client periodically sends whitespace characters over the connection to keep it alive:

final whixp = Whixp(
  jabberID: 'vsevolod@localhost',
  password: 'passwd',
  internalDatabasePath: 'whixp',
  pingKeepAlive: true,
  pingKeepAliveInterval: 300, // seconds, default is 300
);

The keep-alive interval specifies how often (in seconds) the ping signal should be sent. This helps prevent the connection from timing out due to inactivity.

IPv6 Support​

Whixp supports IPv6 connections. To enable IPv6, set the useIPv6 parameter to true:

final whixp = Whixp(
  jabberID: 'vsevolod@localhost',
  password: 'passwd',
  internalDatabasePath: 'whixp',
  useIPv6: true,
);

When enabled, Whixp will attempt to use IPv6 addresses when available, falling back to IPv4 if IPv6 is not supported or available.