# $EPIC: serverctl,v 1.5 2003/03/21 00:32:26 kitambi Exp $
Synopsis:
   $serverctl(<operation> <operand> [<rval>])
   $serverctl(REFNUM <server description|number>)
   $serverctl(GMATCH <group name>)
   $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 works in one of two ways.  When used with a server
     description (see the /server command for information about this), it
     will either return the refnum of a server matching that description, or
     if no such server exists, create one and return that refnum.  When used
     with a number it either returns that number if a server under that
     refnum exists, or the empty string (nothing) if it does not.
   * The GMATCH operation returns a space-separated list of all server
     refnums that belong to the given server-group.
   * The GET/SET operators work by either retrieving or setting,
     respectively, a variety of parameters (described below).  Unless
     otherwise noted, the SET operator causes immediate change and returns 1
     to indicate success.  If a server described by 'refnum' does not exist,
     the queries return failure.
     + 005: Handles individual 005 (PROTOCTL) entries.
       - GET: Returns the specified item from the 005 list, or nothing.
       - SET: Sets the specified item from the 005 list.
     + 005s: Handles the full list of items in the 005 (PROTOCTL) numeric.
       - GET: Returns the complete list.
       - SET: This value cannot be set.
     + AWAY: Handles the server's away message.
       - GET: Returns the away message if it exists, or nothing.
       - SET: Changes the away message.
     + CONNECTED: Handles the server's "connected" status.
       - GET: Returns 1 if the client is connected to the server.
       - SET: This value cannot be set.
     + COOKIE: Handles the TS4 "cookie" for our connection.
       - GET: Returns the cookie if we have one, or nothing.
       - SET: Changes the cookie.  Use this with caution!  You may lose
              saved privileges.
     + GROUP: Handles the server's grouping.
       - GET: Returns the group the server is in.
       - SET: CHanges the group the server is in.
     + ITSNAME: Handles what EPIC thinks the server's name is.
       - GET: Returns the server name.
       - SET: Changes what EPIC thinks the server's name is.  BE CAREFUL
              when using this, as it will most likely result in client
              malfunction.  Use with EXTREME caution!
     + NAME: Handles the hostname used to connect to the server.
       - GET: Returns the hostname.
       - SET: Changes the hostname used.  This does not take effect until
              you reconnect.
     + NICKNAME: Handles the client's nickname on the server.
       - GET: Returns your current nickname.
       - SET: Changes your nickname.
     + PASSWORD: Handles the password used to connect to the server.
       - GET: Returns the password, if any.
       - SET: Changes the password used.  Takes effect when you reconnect.
     + PORT: Handles the port number used to connect to the server.
       - GET: Returns the port number.
       - SET: Changes the port number used.  Takes effect when you reconnect. 
     + QUIT_MESSAGE: Handles the default quit message for the server.
       - GET: Returns the current default.
       - SET: Changes the default quit message for the server.
     + SSL: Handles the SSL status of a server.
       - GET: Returns 1 if the server is being treated as an SSL server, 0
              otherwise.
       - SET: Changes whether the server is being treated as an SSL server
              (only at connect time!).  Setting this to 1 will turn SSL on,
              while setting it to 0 turns SSL off.
     + UMODE: Handles the user mode on the server.
       - GET: Gets the current user mode.
       - SET: This does not work (yet!)
     + USERHOST: Handles what EPIC thinks your hostname on the server is.
       - GET: Returns what EPIC thinks the server feels your hostname is.
       - SET: Chanes what EPIC thinks the server feels your hostname is.
              This may be useful if you wish to manipulate the value used by
              the DCC_USE_GATEWAY_ADDR setting.  Be careful, you may break
              the /DCC command if you are not careful.

Practical:
   This function provides an easy (and sometimes the only) way to change
   certain properties of servers in the client.  Additionally this is
   currently the only way to programatically manage server groups.  It also
   provides a much easier way to create new servers, and do other things.

Examples:
   $serverctl(REFNUM irc.prbh.org:6667::wd)  Creates a server entry for
                                                irc.prbh.org:6667 with
                                                the nickname set as 'wd'.
   $serverctl(SET 1 SSL 1)                      Tells EPIC to use SSL on
                                                server refnum 1.
   $serverctl(GET 2 CONNECTED)                  Tells you if server 2 is
                                                connected.
   $serverctl(GMATCH EFnet)                     Returns a list of servers in
                                                the EFnet group.

See Also:
   server(1); dcc(1); set(4) dcc_use_gateway_addr