1
// *************************************************************************
4
// * File: gsm_sorted_phonebook_base.h
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).
11
// * Author: Peter Hofmann (software@pxh.de)
13
// * Created: 5.6.2000
14
// *************************************************************************
16
#ifndef GSM_SORTED_PHONEBOOK_BASE_H
17
#define GSM_SORTED_PHONEBOOK_BASE_H
19
#include <gsmlib/gsm_util.h>
20
#include <gsmlib/gsm_map_key.h>
29
// a single entry in a phonebook
31
class PhonebookEntryBase : public RefBase
34
bool _changed; // set to true if _telephone or _text changed
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
45
PhonebookEntryBase() :
46
_changed(false), _index(-1), _useIndex(false) {}
48
// convenience constructor
49
PhonebookEntryBase(string telephone, string text, int index = -1) :
50
_changed(false), _telephone(telephone), _text(text),
51
_index(index), _useIndex(false) {}
54
virtual void set(string telephone, string text, int index = -1,
55
bool useIndex = false)
57
virtual string text() const throw(GsmException);
58
virtual string telephone() const throw(GsmException);
60
// return true if both telephone and text are empty
61
bool empty() const throw(GsmException);
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;}
69
// if one of the operands has _useIndex == true
70
// takes _index and e._index into account
71
bool operator==(const PhonebookEntryBase &e) const;
74
int index() const {return _index;}
76
// return true if entry changed
77
bool changed() const {return _changed;}
79
// reset the changed status (ie. if synced to file)
80
void resetChanged() {_changed = false;}
82
// return deep copy of this entry
83
virtual Ref<PhonebookEntryBase> clone();
85
PhonebookEntryBase(const PhonebookEntryBase &e) throw(GsmException);
86
PhonebookEntryBase &operator=(const PhonebookEntryBase &e)
89
virtual ~PhonebookEntryBase() {}
92
// MapKey for sortedPhonebook
94
class SortedPhonebookBase;
95
typedef MapKey<SortedPhonebookBase> PhoneMapKey;
97
// maps text or telephone to entry
99
typedef multimap<PhoneMapKey, PhonebookEntryBase*> PhonebookMap;
101
// iterator for SortedPhonebook that hides the "second" member of the map
103
typedef PhonebookMap::iterator PhonebookMapIterator;
104
class SortedPhonebookIterator : public PhonebookMapIterator
107
SortedPhonebookIterator() {}
108
SortedPhonebookIterator(PhonebookMap::iterator i) :
109
PhonebookMapIterator(i) {}
111
PhonebookEntryBase &operator*()
112
{return *((PhonebookMap::iterator)*this)->second;}
114
PhonebookEntryBase *operator->()
115
{return ((PhonebookMap::iterator)*this)->second;}
118
// virtual base class for sorted phonebooks
120
class SortedPhonebookBase : public RefBase, public NoCopy
124
typedef SortedPhonebookIterator iterator;
125
typedef PhonebookMap::size_type size_type;
127
// return maximum telephone number length
128
virtual unsigned int getMaxTelephoneLen() const = 0;
130
// return maximum entry description length
131
virtual unsigned int getMaxTextLen() const = 0;
134
virtual void setSortOrder(SortOrder newOrder) = 0;
135
virtual SortOrder sortOrder() const = 0;
137
// phonebook traversal commands
138
// these are suitable to use stdc++ lib algorithms and iterators
140
// traversal commands
141
virtual iterator begin() = 0;
142
virtual iterator end() = 0;
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;
150
// existing iterators remain valid after an insert or erase operation
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)
157
virtual iterator insert(iterator position, const PhonebookEntryBase& x)
158
throw(GsmException) = 0;
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;
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;
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;
178
// synchronize SortedPhonebookBase with storage
179
virtual void sync() throw(GsmException) = 0;
181
virtual ~SortedPhonebookBase() {}
184
typedef Ref<SortedPhonebookBase> SortedPhonebookRef;
187
// base factory class for custom backends
188
class CustomPhonebookFactory
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;
197
// registry for custom backends
199
class CustomPhonebookRegistry
201
// registered factories
202
static map<string, CustomPhonebookFactory*> *_factoryList;
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)
212
// return a phonebook object given the backend name and the source
214
static SortedPhonebookRef
215
createPhonebook(string backendName, string source) throw(GsmException);
220
#endif // GSM_SORTED_PHONEBOOK_BASE_H