git.ipfire.org Git - thirdparty/freeswitch.git/blob

   1 // *************************************************************************
   2 // * GSM TA/ME library
   3 // *
   4 // * File:    gsm_sorted_phonebook_base.h
   5 // *
   6 // * Purpose: Virtual base class for alphabetically sorted phonebook
   7 // *          The infrastructure in this module allows custom backends for
   8 // *          storing phonebook entries to be integrated into gsmlib
   9 // *          (eg. LDAP- or RDBMS-based phonebook stores).
  10 // *
  11 // * Author:  Peter Hofmann (software@pxh.de)
  12 // *
  13 // * Created: 5.6.2000
  14 // *************************************************************************
  15
  16 #ifndef GSM_SORTED_PHONEBOOK_BASE_H
  17 #define GSM_SORTED_PHONEBOOK_BASE_H
  18
  19 #include <gsmlib/gsm_util.h>
  20 #include <gsmlib/gsm_map_key.h>
  21 #include <string>
  22 #include <map>
  23 #include <fstream>
  24
  25 using namespace std;
  26
  27 namespace gsmlib
  28 {
  29   // a single entry in a phonebook
  30
  31   class PhonebookEntryBase : public RefBase
  32   {
  33   protected:
  34     bool _changed;              // set to true if _telephone or _text changed
  35     string _telephone;
  36     string _text;
  37     int _index;                 // my position in the phonebook
  38                                 // == -1 if not used (can only happen if
  39                                 // phonebook is read from file)
  40     bool _useIndex;             // compare indices in operator==,
  41                                 // use _index for inserting into
  42                                 // Phonebook
  43
  44   public:
  45     PhonebookEntryBase() :
  46       _changed(false), _index(-1), _useIndex(false) {}
  47
  48     // convenience constructor
  49     PhonebookEntryBase(string telephone, string text, int index = -1) :
  50       _changed(false), _telephone(telephone), _text(text),
  51       _index(index), _useIndex(false) {}
  52
  53     // accessor functions
  54     virtual void set(string telephone, string text, int index = -1,
  55                      bool useIndex = false)
  56       throw(GsmException);
  57     virtual string text() const throw(GsmException);
  58     virtual string telephone() const throw(GsmException);
  59
  60     // return true if both telephone and text are empty
  61     bool empty() const throw(GsmException);
  62
  63     // set to true if operator== should compare the _index as well
  64     void setUseIndex(bool useIndex)
  65       {_useIndex = useIndex;}
  66     bool useIndex() const {return _useIndex;}
  67
  68     // equality operator
  69     // if one of the operands has _useIndex == true
  70     // takes _index and e._index into account
  71     bool operator==(const PhonebookEntryBase &e) const;
  72
  73     // return index
  74     int index() const {return _index;}
  75
  76     // return true if entry changed
  77     bool changed() const {return _changed;}
  78
  79     // reset the changed status (ie. if synced to file)
  80     void resetChanged() {_changed = false;}
  81
  82     // return deep copy of this entry
  83     virtual Ref<PhonebookEntryBase> clone();
  84
  85     PhonebookEntryBase(const PhonebookEntryBase &e) throw(GsmException);
  86     PhonebookEntryBase &operator=(const PhonebookEntryBase &e)
  87       throw(GsmException);
  88
  89     virtual ~PhonebookEntryBase() {}
  90   };
  91
  92   // MapKey for sortedPhonebook
  93
  94   class SortedPhonebookBase;
  95   typedef MapKey<SortedPhonebookBase> PhoneMapKey;
  96
  97   // maps text or telephone to entry
  98
  99   typedef multimap<PhoneMapKey, PhonebookEntryBase*> PhonebookMap;
 100
 101   // iterator for SortedPhonebook that hides the "second" member of the map
 102
 103   typedef PhonebookMap::iterator PhonebookMapIterator;
 104   class SortedPhonebookIterator : public PhonebookMapIterator
 105   {
 106   public:
 107     SortedPhonebookIterator() {}
 108     SortedPhonebookIterator(PhonebookMap::iterator i) :
 109       PhonebookMapIterator(i) {}
 110
 111     PhonebookEntryBase &operator*()
 112       {return *((PhonebookMap::iterator)*this)->second;}
 113
 114     PhonebookEntryBase *operator->()
 115       {return ((PhonebookMap::iterator)*this)->second;}
 116   };
 117
 118   // virtual base class for sorted phonebooks
 119
 120   class SortedPhonebookBase : public RefBase, public NoCopy
 121   {
 122   public:
 123     // iterator defs
 124     typedef SortedPhonebookIterator iterator;
 125     typedef PhonebookMap::size_type size_type;
 126
 127     // return maximum telephone number length
 128     virtual unsigned int getMaxTelephoneLen() const = 0;
 129
 130     // return maximum entry description length
 131     virtual unsigned int getMaxTextLen() const = 0;
 132
 133     // handle sorting
 134     virtual void setSortOrder(SortOrder newOrder) = 0;
 135     virtual SortOrder sortOrder() const = 0;
 136
 137     // phonebook traversal commands
 138     // these are suitable to use stdc++ lib algorithms and iterators
 139
 140     // traversal commands
 141     virtual iterator begin() = 0;
 142     virtual iterator end() = 0;
 143
 144     // the size macros return the number of used entries
 145     virtual int size() const = 0;
 146     virtual int max_size() const = 0;
 147     virtual int capacity() const = 0;
 148     virtual bool empty() const throw(GsmException) = 0;
 149
 150     // existing iterators remain valid after an insert or erase operation
 151
 152     // return position
 153     // insert only writes to available positions
 154     // warning: insert fails silently if size() == max_size()
 155     virtual iterator insert(const PhonebookEntryBase& x) throw(GsmException)
 156       = 0;
 157     virtual iterator insert(iterator position, const PhonebookEntryBase& x)
 158       throw(GsmException) = 0;
 159
 160     virtual PhonebookMap::size_type count(string &key) = 0;
 161     virtual iterator find(string &key) = 0;
 162     virtual iterator lower_bound(string &key) = 0;
 163     virtual iterator upper_bound(string &key) = 0;
 164     virtual pair<iterator, iterator> equal_range(string &key) = 0;
 165
 166     virtual PhonebookMap::size_type count(int key) = 0;
 167     virtual iterator find(int key) = 0;
 168     virtual iterator lower_bound(int key) = 0;
 169     virtual iterator upper_bound(int key) = 0;
 170     virtual pair<iterator, iterator> equal_range(int key) = 0;
 171
 172     virtual size_type erase(string &key) throw(GsmException) = 0;
 173     virtual size_type erase(int key) throw(GsmException) = 0;
 174     virtual void erase(iterator position) throw(GsmException) = 0;
 175     virtual void erase(iterator first, iterator last) throw(GsmException) = 0;
 176     virtual void clear() throw(GsmException) = 0;
 177
 178     // synchronize SortedPhonebookBase with storage
 179     virtual void sync() throw(GsmException) = 0;
 180
 181     virtual ~SortedPhonebookBase() {}
 182   };
 183
 184   typedef Ref<SortedPhonebookBase> SortedPhonebookRef;
 185
 186
 187   // base factory class for custom backends
 188   class CustomPhonebookFactory
 189   {
 190   public:
 191     // return sorted phonebook object given the source specification
 192     // (eg. database name, URL, etc.)
 193     virtual SortedPhonebookRef createPhonebook(string source)
 194       throw(GsmException) = 0;
 195   };
 196
 197   // registry for custom backends
 198
 199   class CustomPhonebookRegistry
 200   {
 201     // registered factories
 202     static map<string, CustomPhonebookFactory*> *_factoryList;
 203
 204   public:
 205     // register a factory class for a specific backend
 206     // (case does not matter for backend name)
 207     static void registerCustomPhonebookFactory(string backendName,
 208                                         CustomPhonebookFactory *factory)
 209       throw(GsmException);
 210
 211
 212     // return a phonebook object given the backend name and the source
 213     // specification
 214     static SortedPhonebookRef
 215     createPhonebook(string backendName, string source) throw(GsmException);
 216   };
 217
 218 };
 219
 220 #endif // GSM_SORTED_PHONEBOOK_BASE_H