include/base.h

   1 /*       +------------------------------------+
   2  *       | Inspire Internet Relay Chat Daemon |
   3  *       +------------------------------------+
   4  *
   5  *  InspIRCd is copyright (C) 2002-2006 ChatSpike-Dev.
   6  *                       E-mail:
   7  *                <brain@chatspike.net>
   8  *                <Craig@chatspike.net>
   9  *
  10  * Written by Craig Edwards, Craig McLure, and others.
  11  * This program is free but copyrighted software; see
  12  *            the file COPYING for details.
  13  *
  14  * ---------------------------------------------------
  15  */
  16
  17 #ifndef __BASE_H__
  18 #define __BASE_H__
  19
  20 #include "inspircd_config.h"
  21 #include <time.h>
  22 #include <map>
  23 #include <deque>
  24 #include <string>
  25
  26 typedef void* VoidPointer;
  27 typedef std::map<std::string,char*> ExtensibleStore;
  28
  29 extern time_t TIME;
  30
  31 /** The base class for all inspircd classes
  32 */
  33 class classbase
  34 {
  35  public:
  36         /** Time that the object was instantiated (used for TS calculation etc)
  37         */
  38         time_t age;
  39
  40         /** Constructor,
  41          * Sets the object's time
  42          */
  43         classbase() { age = TIME; }
  44         ~classbase() { }
  45 };
  46
  47 /** class Extensible is the parent class of many classes such as userrec and chanrec.
  48  * class Extensible implements a system which allows modules to 'extend' the class by attaching data within
  49  * a map associated with the object. In this way modules can store their own custom information within user
  50  * objects, channel objects and server objects, without breaking other modules (this is more sensible than using
  51  * a flags variable, and each module defining bits within the flag as 'theirs' as it is less prone to conflict and
  52  * supports arbitary data storage).
  53  */
  54 class Extensible : public classbase
  55 {
  56         /** Private data store
  57          */
  58         ExtensibleStore Extension_Items;
  59
  60 public:
  61
  62         /** Extend an Extensible class.
  63          *
  64          * @param key The key parameter is an arbitary string which identifies the extension data
  65          * @param p This parameter is a pointer to any data you wish to associate with the object
  66          *
  67          * You must provide a key to store the data as via the parameter 'key' and store the data
  68          * in the templated parameter 'p'.
  69          * The data will be inserted into the map. If the data already exists, you may not insert it
  70          * twice, Extensible::Extend will return false in this case.
  71          *
  72          * @return Returns true on success, false if otherwise
  73          */
  74         template<typename T> bool Extend(const std::string &key, T* p)
  75         {
  76                 /* This will only add an item if it doesnt already exist,
  77                  * the return value is a std::pair of an iterator to the
  78                  * element, and a bool saying if it was actually inserted.
  79                  */
  80                 return this->Extension_Items.insert(std::make_pair(key, (char*)p)).second;
  81         }
  82
  83         /** Extend an Extensible class.
  84          *
  85          * @param key The key parameter is an arbitary string which identifies the extension data
  86          *
  87          * You must provide a key to store the data as via the parameter 'key', this single-parameter
  88          * version takes no 'data' parameter, this is used purely for boolean values.
  89          * The key will be inserted into the map with a NULL 'data' pointer. If the key already exists
  90          * then you may not insert it twice, Extensible::Extend will return false in this case.
  91          *
  92          * @return Returns true on success, false if otherwise
  93          */
  94         bool Extend(const std::string &key)
  95         {
  96                 /* This will only add an item if it doesnt already exist,
  97                  * the return value is a std::pair of an iterator to the
  98                  * element, and a bool saying if it was actually inserted.
  99                  */
 100                 return this->Extension_Items.insert(std::make_pair(key, (char*)NULL)).second;
 101         }
 102
 103         /** Shrink an Extensible class.
 104          *
 105          * @param key The key parameter is an arbitary string which identifies the extension data
 106          *
 107          * You must provide a key name. The given key name will be removed from the classes data. If
 108          * you provide a nonexistent key (case is important) then the function will return false.
 109          * @return Returns true on success.
 110          */
 111         bool Shrink(const std::string &key);
 112
 113         /** Get an extension item.
 114          *
 115          * @param key The key parameter is an arbitary string which identifies the extension data
 116          * @param p If you provide a non-existent key, this value will be NULL. Otherwise a pointer to the item you requested will be placed in this templated parameter.
 117          * @return Returns true if the item was found and false if it was nor, regardless of wether 'p' is NULL. This allows you to store NULL values in Extensible.
 118          */
 119         template<typename T> bool GetExt(const std::string &key, T* &p)
 120         {
 121                 ExtensibleStore::iterator iter = this->Extension_Items.find(key);
 122                 if(iter != this->Extension_Items.end())
 123                 {
 124                         p = (T*)iter->second;
 125                         return true;
 126                 }
 127                 else
 128                 {
 129                         p = NULL;
 130                         return false;
 131                 }
 132         }
 133
 134         /** Get an extension item.
 135          *
 136          * @param key The key parameter is an arbitary string which identifies the extension data
 137          * @return Returns true if the item was found and false if it was not.
 138          *
 139          * This single-parameter version only checks if the key exists, it does nothing with
 140          * the 'data' field and is probably only useful in conjunction with the single-parameter
 141          * version of Extend().
 142          */
 143         bool GetExt(const std::string &key)
 144         {
 145                 return (this->Extension_Items.find(key) != this->Extension_Items.end());
 146         }
 147
 148         /** Get a list of all extension items names.
 149          * @param list A deque of strings to receive the list
 150          * @return This function writes a list of all extension items stored in this object by name into the given deque and returns void.
 151          */
 152         void GetExtList(std::deque<std::string> &list);
 153 };
 154
 155 /** BoolSet is a utility class designed to hold eight bools in a bitmask.
 156  * Use BoolSet::Set and BoolSet::Get to set and get bools in the bitmask,
 157  * and Unset and Invert for special operations upon them.
 158  */
 159 class BoolSet : public classbase
 160 {
 161         char bits;
 162
 163  public:
 164
 165         /** The default constructor initializes the BoolSet to all values unset.
 166          */
 167         BoolSet();
 168
 169         /** This constructor copies the default bitmask from a char
 170          */
 171         BoolSet(char bitmask);
 172
 173         /** The Set method sets one bool in the set.
 174          *
 175          * @param number The number of the item to set. This must be between 0 and 7.
 176          */
 177         void Set(int number);
 178
 179         /** The Get method returns the value of one bool in the set
 180          *
 181          * @param number The number of the item to retrieve. This must be between 0 and 7.
 182          *
 183          * @return True if the item is set, false if it is unset.
 184          */
 185         bool Get(int number);
 186
 187         /** The Unset method unsets one value in the set
 188          *
 189          * @param number The number of the item to set. This must be between 0 and 7.
 190          */
 191         void Unset(int number);
 192
 193         /** The Unset method inverts (flips) one value in the set
 194          *
 195          * @param number The number of the item to invert. This must be between 0 and 7.
 196          */
 197         void Invert(int number);
 198
 199         /** Compare two BoolSets
 200          */
 201         bool operator==(BoolSet other);
 202
 203         /** OR two BoolSets together
 204          */
 205         BoolSet operator|(BoolSet other);
 206
 207         /** AND two BoolSets together
 208          */
 209         BoolSet operator&(BoolSet other);
 210
 211         /** Assign one BoolSet to another
 212          */
 213         bool operator=(BoolSet other);
 214 };
 215
 216
 217 #endif