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)