Special Topic:

Each server in your server list has a state that it is in.

The valid states are:

Name	Description
CREATED	The initial state while it is being added to the server list
RECONNECT	Ready to be used: will be connected to when window points at it
DNS	Server being brought up: Nonblocking DNS lookup in progress
CONNECTING	Server being brought up: Nonblocking connect in progress
SSL_CONNECTING	Server being brought up: Nonblocking SSL negotation in progress
REGISTERING	Server being brought up: IRC Protocol registration with the server in progress
SYNCING	Connected to irc: Not all operations can be performed yet
ACTIVE	Connected to irc: All operations are supported
EOF	The server has rejected us and closed the network connection
ERROR	We have rejected the server and are closing the network connection
CLOSING	Disconnecting from irc: Not all operations may be performed
CLOSED	Disconnected from irc: No operations may be performed
DELETED	The final state while it is being removed from server list

Connecting to a server:

Servers are not automatically connected to when you add them to the server list. Instead, they are in the RECONNECT state which is quiescent. Whenever you attach any window to the server when it is in the RECONNECT state, it will automatically come up.

Automatic Reconnection during connection:

Connection to a server is a complicated concept. It involves the whole action from when a server has a window and is in RECONNECT, until either the server reaches SYNCING or CLOSED with no more addresses.

When a server with a window is in RECONNECT, it switches to DNS and looks up the addresses for its hostname. This returns one or more addresses. For each of the addresses returned, the server switches to CONNECTING and continues on until either it reaches SYNCING or CLOSED for that address.

If SYNCING is reached, the server throws away any remaining addresses. If CLOSED is reached, the client advances to the next address and goes back to CONNECTING. This continues until either SYNCING is reached or CLOSED is reached and there are no more addresses left to try.

All of the above is to be considered a single “connection attempt”, and although all of the above actions are nonblocking and asynchronous, until one of the two terminal conditions are reached, the client cannot be thwarted.

Terminal condition one, success:

  on server_state "% % SYNCING" {
     xecho -b Server $0 has been accepted onto irc.
  }

Terminal condition two, failure:

  on server_state "% % CLOSED" {
     if (serverctl(GET $0 ADDRSLEFT) == 0) {
         xecho -b Server $0 could not connect to irc.  Help me!
     }
  }

Remember, CLOSED is not a terminal condition unless ADDRSLEFT is also 0!

You, the user, have the ability to terminate a connection to a particular address by using disconnect. See the help files for disconnect and reconnect for important distinctions between the two.

Disconnecting from a server:

If we are accepted onto irc, then the connection stays open until either the server rejects us (closes our connection) or we reject the server (due to a network error). When the connection is severed, the server goes into either EOF or ERROR state to tell you who is closing, and then to the CLOSING state, and finally the CLOSED state.

No automatic reconnection:

Once a server is in the CLOSED state and there are no more addresses left to use (either because we have tried them all, or because we reached the SYNCING state), it cannot be used again until it is reset to the RECONNECT state.

You can put a server in the RECONNECT state with

reconnect refnum
server +refnum
window server refnum

Script support:

The reconnect_script implements epic4 behavior of automatic reconnecting to servers when you are disconnected. Ordinarily the above technical information is not interesting to the user, but only to those who need to implement their own scripted reconnection scripts.

Language Support:

An on server_status event is thrown whenever the status of a server changes.

The $serverctl(GET refnum STATUS) function can be used to query the current state of the server.

History:

Server states are an EPIC5 feature which were invented during the nonblocking connection project. They have been expanded during the nonblocking dns project, the nonblocking ssl project, and the reconnect script project.

Table of Contents