======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 command|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 command|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.