This document describe\s the developer's interface to class xClient. Anyone interested in creating services clients for GNUWorld definitely needs to read this. The document provides a thorough description of the design and functioning of xClient.
Please contact us if you have further documentation requirements or questions about current documentation.
Here is an index to the topics covered in this discussion.
To build your own services bot, you must use the server framework provided by GNUWorld. This is a nice and relatively simple framework that provides all the options you would need for any (?) type of service bot.
The first thing you need to do is subclass xClient. xClient provides a (still developing) set of functionality. Contained within the xClient base class are all of the primary data variables and methods that any services client will need. Each new client may of course define new variable and methods to suit its own needs.
Each client is free to implement its own command execution and distribution system. The server delivers messages and events to its clients by way of handler methods. These mostly begin with "On." For example, OnConnect(), OnPrivateMessage(), OnCTCP(), OnChannelEvent(), etc. GNUWorld provides a powerful and simple event and message distribution system. All client events are delivered to the client in question. The xClient may also choose to register for any of a growing number of possible network events. In this way, the client has full knowledge of the network global state (see Distributed Operating Systems and Algorithms).
Description of the available xClient methods proceeds from public methods to private ones. However, we first begin with the constructors and operator=.
First, we begin with the constructor.
This constructor receives a single argument, the filename of a configuration file. The base class constructor will read the basic and required client information, such as nickname, username, hostname, description.
The next constructor of interest follows. This method has been disabled completely.
The default constructor is protected, but implemented (it's empty). This is so that users may subclass xClient in a module.
All variables are given protected access. This is done to enhance encapsulation, yet allow subclassing with full access to the base class. It is highly suggested that all subclasses be written with the strictest attention to these philosophies. Most variables may be accessed through an accessor (get) method. Those variables that are not given a mutator (set) method are internal to xClient. It is recommended that access to these variables be judiciously decided upon.
Here is a brief description of the variables available in xClient. Given is the variable type following by the variable name.
modeType is the same type as class iClient's modeType. This is a variable sufficiently sized and formed to hold a bitmask representing the possible modes a client may need. Defined in class iClient also are bitmask const static variable instances used to access and mutate the client's state through the manipulation of its internal (mode) variable. For a more detailed discussion of these variables, see the documentation for class iClient.
MyUplink is a pointer to the one and only xServer. This represents the server to which the virtual client is attached. MyUplink is the server proper. xServer provides a variety of useful methods and data for use by xClient virtual clients. MyUplink also provides several utility methods for network, server, and client information.
MyUplink is instantiated once, in main() (main.cc). This is the only instance of this class, though it is not needed that it be a Singleton (Design Patterns, GOF).
Each of these string class instances (imported from namespace std) represents one of any IRC client's most vital state variables. These should be obvious.
Connected is true when the xClient is connected to an xServer. Note that this is NOT a reflection of whether xServer is connected to a physical network. This variable refers only to its ownership by an xServer. This is initially false, and set by the base class xClient to true when xClient::Connect() is called. This method is only called by xServer when it connects to the network. More on this function later.
This is the client's current user mode, as seen by the rest of the network. This is a bitmask of type modeType, defined above, and originally in iClient. iClient also defines some of the possible values for variables of this type. It is recommended that additional mode types not be added for class xClient subclasses as this would indicate a change in the protocol supported by the xServer.
(intYY) is the integer representation of the xClient's uplink's server numeric. This is currently a two character numeric, and is represented by have two 'Y's in the variable name. (intYY) should be equal to MyUplink's xServer::getIntYY(). It is also kept in class xClient for convenience.
This variable represents the xClient's individual numeric on this server. It is currently a three character variable, as indicated by the three 'XXX's. This variable uniquely (as per the Undernet IRC Protocol) identifies the client within the clients on this server.
(charYY) This is the two character representation of the client's server numeric. It is provided here for convenience for the programmer.
(charXXX) This is the three character representation of the client's numeric. It is provided here for convenience.