Table of Contents
# $EPIC: serverctl.txt,v 1.10 2010/03/22 00:52:57 jnelson Exp $
Synopsis:
$serverctl(REFNUM <server refnum>)
$serverctl(REFNUM <name>)
$serverctl(REFNUM <name>:<port>)
$serverctl(OMATCH <pattern>)
$serverctl(IMATCH <pattern>)
$serverctl(GMATCH <pattern>)
$serverctl(LAST_SERVER)
$serverctl(FROM_SERVER)
$serverctl(MAX)
$serverctl(ALLGROUPS)
$serverctl(GET <refnum> <param>)
$serverctl(SET <refnum> <param> <val>)
Technical:
This function is a low-level interface to the client's server structure.
The REFNUM operation takes a server refnum, and returns that refnum if the refnum is valid, or returns the empty string if the refnum is invalid.
The REFNUM operation takes a regular old server description, but only the first two fields are used. The first field should contain a wildcard pattern that will match either an “ourname”, an “itsname”, a group, or an alternate name. If you specify a port number, then the server has to match the port number as well as the host. The operation returns a refnum to an open server if it can, and to a closed server if it must. It returns the empty string if nothing is found.
The REFNUM operation can take a port after the server name, and then any server must match the port as well as the server name. Normally the port is ignored.
The OMATCH, IMATCH, and GMATCH operations match a wildcard pattern against each server's “ourname”, “itsname”, and “groupname” respectively. The return value is a space separated list of server refnums that match.
The LAST_SERVER operation returns the refnum of the last irc server that sent us some data. This cannot be changed by the user.
The FROM_SERVER operation returns the current operative server. This can be changed by the user with XEVAL -s.
The MAX operation returns the highest server refnum in use. This can be used to bound a loop to iterate over all servers.
The ALLGROUPS operation returns a unique word list of all of the server groups that are in use. At this time, this operation does not take any arguments, but that will probably change in the future. You should not pass any arguments to this operation for now.
The GET and SET operations read and write respectively, attributes about a server refnum. Server refnum -1 always refers to the FROM_SERVER.
| Attribute name | Get | Set | Description |
|---|---|---|---|
| ADDRFAMILY | Get | When server open, the protocol - Either “ipv4”, “ipv6”, “unix”, or “unknown” | |
| ADDRSLEFT | Get | When connecting to server, the number of round-robin addresses remaining from the DNS lookup | |
| ALTNAME | Get | Set | Add a user-specified “alternate server name” (can add any number) |
| ALTNAMES | Get | Return all alternate server names | |
| ALTNAMES | Set | Delete all alternate server names and add these new ones | |
| AUTOCLOSE | Get | Set | When 1 (default), a server closes when “no windows connected to this server”. When 0, a server will not close when it has no windows – you have to disconnect from it. |
| AWAY | Get | Set | The server's away message. SETting this will send an AWAY message to the server. SETting this to the empty string clears the AWAY message. |
| CONNECTED | Get | 1 if an RFC1459 protocol session is active (“on irc”) and 0 if not | |
| COOKIE | Get | Set | The TS4 server cookie |
| DEFAULT_REALNAME | Get | Set | The REALNAME that will be used next time you connect to this server |
| FULLDESC | Get | The Fully Qualified Server Description for a server, suitable for recreating a server list file. | |
| GROUP | Get | Set | The server group |
| ITSNAME | Get | Set | The name the server calls itself in protocol messages |
| ISONLEN | Get | Set | Maximum number of nicks in one ISON request (minimum: 100) |
| LOCALPORT | Get | When connected, the port number on our host we are using. | |
| MAXCACHESIZE | Get | Set | The maximum number of people who can be in a channel that does userhost caching. Channels bigger than this are not cached. Set to 0 to turn off userhost caching entirely. |
| MAXISON | Get | Set | The maximum size of the ISON queue. ISON commands are ignored when the queue is full. |
| MAXUSERHOST | Get | Set | The maximum size of the USERHOST queue. USERHOST commands are ignored when the queue is full. |
| NAME | Get | Set | The hostname that we use to connect to the server |
| NICKNAME | Get | Set | Our official nickname (pending nicknames are not returned) |
| OPEN | Get | 1 if the server connecting or connected; 0 if the server is closed and at rest | |
| PADDR | Get | Server's Presentation Address, ie, “1.2.3.4” for ipv4 or “2600::1” for ipv6. | |
| PASSWORD | Get | Set | The rfc1459 password we use to connect to the server. |
| PORT | Get | Set | The port on the server's hostname we connect to |
| PRIMARY | Set | Make this server the primary server | |
| PROTOCOL | Get | Either “IRC” or “IRC-SSL” | |
| QUIT_MESSAGE | Get | Set | The message we will use when we QUIT |
| REALNAME | Get | Get the current REALNAME (if you're connected) | |
| REALNAME | Set | (Backwards compatability only) Old name for DEFAULT_REALNAME | |
| SSL | Get | Set | The “type” field from the server description, either “IRC” or “IRC-SSL”. |
| SSL_ACCEPT_CERT | Get | Set | Is this cert headed for acceptance? 0 (no) 1 (yes) |
| SSL_CERT_HASH | Get | The certificate's hash | |
| SSL_CHECKHOST_ERROR | Get | Hostname Mismatch error - 0 (no) 1 (yes) | |
| SSL_CIPHER | Get | The encryption cipher being used | |
| SSL_ISSUER | Get | Who issued the cert | |
| SSL_ISSUER_URL | Get | Who issued the cert (url-encoded) | |
| SSL_MOST_SERIOUS_ERROR | Get | The OpenSSL error code of the most serious error 18 (self-signed) and 62 (hostname mismatch) are considered non-serious (routine) errors | |
| SSL_OTHER_ERROR | Get | Any other (serious) error - 0 (no) 1 (yes) | |
| SSL_PEM | Get | The certificate (in PEM format) | |
| SSL_PKEY_BITS | Get | The bits in the public key | |
| SSL_SANS | Get | Subject Alternate Names in the cert | |
| SSL_SELF_SIGNED_ERROR | Get | Self-signed error - 0 (no) 1 (yes) | |
| SSL_SUBJECT | Get | Who the cert was issued to | |
| SSL_SUBJECT_URL | Get | Who the cert was issued to (url-encoded) | |
| SSL_VERIFY_ERROR | Get | Any error at all - 0 (no) 1 (yes) | |
| SSL_VERSION | Get | What version of SSL being used (ie, TLSv1.2) | |
| STATE | Get | The operational status of a server: see server state. | |
| STATUS | Get | (Backwards compatability only) Old name of STATE | |
| UMODE | Get | Set | The protocol user mode. Use MODE to change. |
| UNIQUE_ID | Get | Set | The IRCNet unique nickname identifier |
| USERHOST | Get | Set | The userhost the server says we're using |
| VERSION | Get | Set | The version of irc software the server is using |
| VHOST | Get | Set | |
| 005s | Get | All of the 005s the server supports | |
| 005 <token> | Get | Set | A particular 005 the server supports |
Examples:
Return the first server entry for irc.prbh.org on any port
$serverctl(REFNUM irc.prbh.org)
Tell EPIC to use SSL on server refnum 1
$serverctl(SET 1 SSL 1)
Return 1 if we can send irc commands to server 2, return 0 if not.
$serverctl(GET 2 CONNECTED)
Returns all refnums in server group “EFnet”
$serverctl(GMATCH EFnet)