void Auth_VerifyAndSendMSG(Auth_TUHCB*);
	friend of Auth_TUser
	Used as a Auth_TUHCB callback function by Auth_TUser::SendMessage
	in the event that we aren't tracking that user, but the user has the
	security setting turned off. This determines if the userhost info
	matches what we remember for this user, and if so delivers the message.
void Auth_Init();
	Perform initialization for the Authentication system. At present
	this calls the data subsystem to load the userlist, and initializes
	the command subsystem.
void Auth_Connect();
	Handles events the Authentication system needs to do on connecting to
	IRC. At present, this is a no-op.
void Auth_Disconnect(const char *);
	Handles cleanup from our being disconnected from IRC. At present,
	it flushes the tracking information from the userlist, and destroys
	all tracking tickets and unused USERHOST callbacks.
TF Auth_Add(void **tref, const char *acct, const char *pass);
	Called from cmd/authcmd.cc (AUTH LOGIN). tref is a pointer to an
	Auth_PTicket. This function calls Auth_TUser::Login to log a user
	into the system, and if successful deletes the unneeded tracking
	ticket and returns TRUE with tref now pointing to the appropriate
	Auth_PUser.
void Auth_Track(const char *nick, const char *channel, TF flag);
      In the case where flag is TRUE:
	If nick is our own, do nothing. Otherwise, first see if we have
	a user we are tracking by this nick. If we are tracking them in
	channel, do nothing. If we are tracking them elsewhere, call
	Auth_TUser::AddTracking to add channel to the list. Next, check
	to see if we have a tracking ticket for this nick. If so, and we
	are tracking them in channel, do nothing. If we are tracking them
	elsewhere, call Auth_TTicket::AddTracking to add channel to the
	list. Finally, perform a USERHOST lookup to get the necessary data
	to start a new tracking ticket.
      In the case where flag is FALSE:
	First, see if a user is being tracked under nick. If so, then if
	channel==NULL we call Auth_TUser::FlushTracking, otherwise we use
	Auth_TUser::RemTracking to remove channel. Next, see if a tracking
	ticket exists for that nick. If so, then if channel==NULL we call
	Auth_TTicket::FlushTracking, otherwise Auth_TTicket::RemTracking.
void Auth_TrackCR(Auth_PUHCB);
	This is used as a callback from Auth_Track's USERHOST request.
	If a user without security set is matched by the userhost info,
	we start tracking that user; otherwise, we create a new tracking
	ticket with the info we've collected.
void Auth_TrackPr(const char *prefix, const char *channel);
	This works similarly to Auth_Track with flag==TRUE, but takes a
	prefix instead of a nick. This should be called when the message
	we're responding to has a valid prefix associated with it. The main
	difference is the lack of a USERHOST request to obtain userhost info
	from the nick, since the prefix includes this information.
void Auth_RemTrack(const char *channel);
	This function is called if we leave a channel. It systematically
	removes channel from the tracking lists of all users and tickets.
void Auth_FlushTrack();
	This function is to be used when we are disconnected from the
	server. At the moment this is fairly meaningless, but will be
	necessary for AUTO_RECONNECT implementation.
void Auth_Rem(void *ticket, uint8 auth);
	Called by the AUTH LOGOUT command. Creates a new Auth_TTicket,
	transfers the channel list from the user, and then logs out the
	user. void *ticket is an Auth_PUser in this case.
void Auth_Userhost(const char *nick, const char *user, const char *host);
	Performs a call to static function Auth_TUHCB::UHCR(). Used to
	process USERHOST responses from the server.
void Auth_Nick(const char *prefix, const char *nick);
	Called when we see a user change their nick. Used to update 
	tracking.
void Auth_Cleanup();
	Perform cleanup of the Authentication system. At present, simply
	calls Auth_TUser::FlushList(). It is assumed that this function is
	called only after Auth_Disconnect, and only in the event that the
	bot is about to shut down.
void Auth_DCCRequest(const char *nick, void *cookie);
	Called when someone tries to establish a DCC CHAT with us. If we
	can find a valid matching user, we accept, otherwise, we reject.
	If necessary this version uses USERHOST to verify the user.
void Auth_DCCRequestCR(Auth_PUHCB);
	Callback for USERHOST request made by Auth_DCCRequest
void Auth_DCCRequestPfx(const char *prefix, void *cookie);
	Same as Auth_DCCRequest, except that no USERHOST request is used.
void Auth_DCCEstablished(void *cookie);
	Called when a user accepts a DCC CHAT we were instructed to offer.
void Auth_DCCLost(void *cookie);
	Called when a DCC CHAT connection is lost or remotely closed.
void Auth_CmdResult(void *, uint8, const char *);
	The command subsystem uses this function to provide results back
	to the user who invoked the command.
void Auth_DCCMessage(void *cookie, const char *message);
	This is called when we receive a message over a DCC CHAT connection.
void Auth_IRCMessage(const char *prefix, const char *message);
	This is called when we receive a private message over IRC. Both
	Auth_IRCMessage and Auth_DCCMessage are responsible for delivering
	user commands to the command subsystem.
void Auth_NotifyMaster(const char *message);
	This is called to send a message to the bot master. Message can only
	be delivered if the bot master is properly logged in.

class Auth_TUser:
Auth_TUser(const char *s_acct, const char *s_pass, TF s_master);
	Constructor for Auth_TUser. s_acct is the name of the user, s_pass
	is the user's password, s_master is true if this is the master account.
	This should only be invoked in loaddata.cc when the userlist is
	retrieved, or if the master account requests a new account to be
	added (must be written to disk as well in this case).
	Note: Only one account may have s_master as true. If s_master is
	passed as true for more than one call to this function, an error will 
	be generated and the program will exit. Also, no two users may have 
	the same name. If s_acct is the same for more than one call to this
	function, an error will be generated and the program will exit.
static void Delete(Auth_PUser user);
	Cleans up and deletes a user from the list. This will maintain the
	integrity of the list, so it can be called in an arbitrary order;
	however, it is generally only used when preparing to end the program.
static void FlushList();
	Calls Auth_TUser::Delete on each user in the list. Used for program
	cleanup.
const char * GetAcct();
	returns the name of the user.
static inline Auth_PUser GetFirst();
	returns the first user in the list.
static inline Auth_PUser GetLast();
	returns the last user in the list.
static inline uint16 GetLength();
	returns the length of the list.
static Auth_PUser GetMaster();
	returns the master account.
inline Auth_PUser GetNext();
	returns the next user in the list.
const char * GetNick();
	returns the user's current nick.
inline Auth_PUser GetPrev();
	returns the previous user in the list.
static Auth_PUser GetUser(const char *s_acct);
	If s_acct is NULL, this is the same as Auth_TUser::GetFirst. Otherwise
	this searches for a user entry with an account name matching s_acct.
	returns the appropriate Auth_PUser or NULL if none is found. I must
	have forgotten about the other GetUser when I put this in, but since
	this has an argument, function overloading saves us from a problem.
	I might rename this in the future, but probably not...
const char * GetUser();
	returns the user's IRC userid string.
const char * GetHost();
	returns the user's hostname.
IRC_PCL GetChans();
	returns the list of channels we currently see this user in.
TF Login(const char *s_pass, const char *s_nick, const char *s_user, 
	 const char *s_host, IRC_PCL s_chans);
	Called by Auth_Add. s_pass is the password
	provided by the user; s_nick, s_user, and s_host are the nick,
	user, and host fields from the tracking ticket. s_chans is the
	channel list from the tracking ticket, or NULL if the ticket is
	for a user we don't see in a channel. If s_pass does not match
	the password passed by the constructor, login fails (return FALSE).
	Login also fails if the user has the security flag set and s_chans
	is NULL. Otherwise, we update the user with the information
	passed to the function and return TRUE.
void Logout();
	Called from cmd/authcmd.cc (AUTH LOGOUT). This clears the nick,
	user, and host entries for this user, and discards the channel list.
	If there is a DCC CHAT open it is closed. NOTE that we do NOT clean
	up the chans list; this will generally have been placed in a tracking
	ticket before Auth_TUser::Logout() is called.
static Auth_TUser * MatchNick(const char *, TF flag = FALSE);
	Finds the user tracked under the given nick. If flag is TRUE, will
	also match users who were last seen under the nick who are no longer
	being tracked, provided that they do not have the security option set.
static Auth_TUser * MatchUH(const char *, const char *);
	Finds a user by last known user and host info. Primarily used in
	conjunction with MatchNick(nick, TRUE) to match users who are not
	currently being tracked. Will only match users without the security
	option set.
static Auth_TUser * MatchPrefix(const char *);
	Combines MatchNick and MatchUH. Called when we have the whole prefix
	by which to identify a user.
static Auth_TUser * MatchDCCCookie(void *, TF flag = FALSE);
	Finds the user associated with a DCC CHAT connection. If flag is TRUE,
	this will also match stale DCC cookies, for use in cleanup functions.
void AddTracking(const char *channel);
	Adds channel to the list of channels we're tracking this user in.
	It is incorrect to call this function if chans==NULL. In this case
	use Auth_TUser::StartTracking.
void RemTracking(const char *channel);
	If channel is in the list of channels in which we see this user,
	delete it from the list.
void ChangeTracking(const char *s_nick);
	Replaces the IRC nickname for the user with s_nick. Used to respond
	to NICK messages for tracked users.
void StartTracking(const char *channel, const char *s_nick);
	Begin tracking this user in channel under the IRC nick s_nick.
	This should not be called if we are already tracking this user.
void FlushTracking();
	Flushes the list of channels we're tracking this user in. If the
	security flag is set, we also forget the nickname under which we were 
	tracking this user.
static void FlushAllTracking();
	Calls Auth_TUser::FlushTracking for all users we are currently
	tracking. Used in the event we're disconnected from IRC.
TF IsTracking(const char *channel) const;
	If channel==NULL, returns TRUE if we are tracking at all. Otherwise,
	returns TRUE if channel matches the name of a channel in which we
	are tracking this user.
void * RegisterDCC(void *cookie);
	Sets a DCC cookie. Returns the previous cookie. The DCC cookie is
	an arbitrary pointer used to identify DCC sessions. What this
	cookie actually contains will depend on the specific low-level IRC
	interface in use. We only require that it be be unique (i.e. that
	no two users get the same pointer) and that the same pointer (not
	just pointers to the same data) is used for all requests regarding
	the DCC session.
void SetDCCStatus(TF flag);
	If flag is TRUE, and dcc_cookie!=NULL, set dcc_active=TRUE. This
	indicates we have an actual DCC CHAT connection with this user and
	should use it instead of NOTICE to communicate with this user.
	If flag is FALSE, set dcc_active=FALSE. If dcc_cookie!=NULL, we
	close or reject the DCC CHAT as appropriate, and set dcc_cookie=NULL.
TF GetDCCStatus() const;
	Returns TRUE if we have an active DCC CHAT connection.
void SendMessage(const char *message);
	Sends the text in message to the user. If there is an active DCC CHAT
	connection, we send it via that DCC CHAT. Otherwise, we send a NOTICE
	(or MSG if usemsg is TRUE). In the event that a user is no longer
	being tracked, the message will be sent only if security==FALSE and
	we can successfully verify that the user at the last known nick has
	the correct userhost info.

class Auth_TTicket:
Auth_TTicket(const char *s_nick, const char *s_user, const char *s_host, 
	     const char *channel, IRC_PCL s_chans = NULL);
	Constructor for Auth_TTicket. This is called whenever we see someone
	new (not associated with an existing user account or tracking ticket).
	s_nick is the IRC nickname we see for them. s_user is the IRC userid
	string we see for them. s_host is the hostname we see for them. If
	s_chans is not NULL then it is used as the list of channels we see them
	in. This will generally only be used during user Logout. If chans is
	NULL (the default) then channel is the name of the channel we see
	someone in. In the special case where someone sends a message to us
	out of the blue, we create a ticket with "boguschan" as the channel
	name.
static void CleanStale();
	If there is a "stale" ticket (one scheduled for deletion) this
	function calls Auth_TTicket::Delete on it.
static void Delete(Auth_PTicket ticket);
	Deletes a tracking ticket while maintaining list integrity. This
	may be called on tickets in any order. NOTE that this does not
	do cleanup of the chans list! This is because tracking tickets are
	usually deleted either 1) when a user logs in, in which case the
	chans list is moved the the Auth_TUser entry; or 2) when the last
	channel in the chans list is deleted, in which case the list is
	already cleaned up.
static void DeleteMe(Auth_PTicket s_stale);
	Calls Auth_TTicket::CleanStale and then marks s_stale as
	being "stale". This is used in place of Auth_TTicket::Delete in cases
	where execution is still in the middle of a function belonging to
	the passed ticket. I don't quite remember now why I made this static...
	come to think of it, I don't even remember why I made this public...
static void FlushList();
	This deletes all tracking tickets. Unlike Auth_TTicket::Delete, we
	clean up the chans list in each ticket.
static Auth_TTicket * MatchNick(const char *);
	Finds the tracking ticket for a given nick.
static inline Auth_TTicket * GetFirst();
	returns the first tracking ticket in the list.
static inline Auth_TTicket * GetLast();
	returns the last tracking ticket in the list.
inline Auth_TTicket * GetNext();
	returns the next tracking ticket in the list.
inline Auth_TTicket * GetPrev();
	returns the previous tracking ticket in the list.
const char * GetNick() const;
	returns the IRC nick we're tracking.
const char * GetUser() const;
	returns the IRC userid string we see for this nick.
const char * GetHost() const;
	returns the hostname we see for this nick.
IRC_PCL GetChans();
	returns the list of channels in which we are tracking this nick.
void AddTracking(const char *channel);
	Adds channel to the list of channels in which we are tracking this
	nick.
void RemTracking(const char *channel);
	If channel is in the list of channels in which we are tracking this
	nick, delete it from the list. If this is the only channel left in
	this list, Auth_TTicket::DeleteMe is called.
void ChangeTracking(const char *s_nick);
	Changes the IRC nick we are tracking. Used to respond to NICK messages
	for people we are tracking.
TF IsTracking(const char *channel) const;
	If called in a stale ticket, returns FALSE automatically. Otherwise,
	returns TRUE if we are tracking this person in channel.
void FlushTracking();
	Deletes the ticket, after flushing the list of channels. NOTE that
	Auth_TTicket::Delete and Auth_TTicket::DeleteMe do NOT flush the
	list of channels but assume instead that the calling function is
	doing something with them.
void SendMessage(const char *message);
	Sends a NOTICE to the tracked user with the text contained in message.

class Auth_TUHCB:
Auth_TUHCB(void (*fun)(Auth_TUHCB *), const char *s_nick);
	Establishes a USERHOST callback handler. fun is the function to call
	once we have obtained the user and host info for s_nick. This object
	must be constructed before calling IRC_Userhost to insure that we know
	what to do with the USERHOST response when it arrives.
static void Delete(Auth_TUHCB *);
	Cleanly removes an Auth_TUHCB object from the list, and destructs it.
static void FlushList();
	Systematically deletes all Auth_TUHCB objects.
static inline Auth_TUHCB * GetFirst();
	returns the first callback ticket in the list.
inline Auth_TUHCB * GetNext();
	returns the next callback ticket in the list.
inline Auth_TUHCB * GetPrev();
	returns the previous callback ticket in the list.
inline const char * GetNick() const;
	returns the nick of the userhost query.
inline const char * GetUser() const;
	returns the obtained IRC userid string.
inline const char * GetHost() const;
	returns the obtained hostname.
static void UHCR(const char *, const char *, const char *);
	Called to handle USERHOST responses. Finds an Auth_TUHCB object
	matching the USERHOST response's nick, assigns the obtained user
	and host to that object, and calls the callback function whose
	pointer is stored in the object.

@(#) $Id$
