| -rw-r--r-- | kabc/addressbook.h | 337 |
1 files changed, 337 insertions, 0 deletions
diff --git a/kabc/addressbook.h b/kabc/addressbook.h new file mode 100644 index 0000000..3383fc0 --- a/dev/null +++ b/kabc/addressbook.h @@ -0,0 +1,337 @@ +/* + This file is part of libkabc. + Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ + +/* +Enhanced Version of the file for platform independent KDE tools. +Copyright (c) 2004 Ulf Schenk + +$Id$ +*/ + +#ifndef KABC_ADDRESSBOOK_H +#define KABC_ADDRESSBOOK_H + +#include <qobject.h> + +#include <kresources/manager.h> +#include <qptrlist.h> + +#ifndef KAB_EMBEDDED + +#else //KAB_EMBEDDED +#endif //KAB_EMBEDDED + + +#include "addressee.h" +#include "field.h" + +namespace KABC { + +class ErrorHandler; +class Resource; +class Ticket; + +/** + @short Address Book + + This class provides access to a collection of address book entries. +*/ +class AddressBook : public QObject +{ + Q_OBJECT + + friend QDataStream &operator<<( QDataStream &, const AddressBook & ); + friend QDataStream &operator>>( QDataStream &, AddressBook & ); + friend class StdAddressBook; + + public: + /** + @short Address Book Iterator + + This class provides an iterator for address book entries. + */ + class Iterator + { + public: + Iterator(); + Iterator( const Iterator & ); + ~Iterator(); + + Iterator &operator=( const Iterator & ); + const Addressee &operator*() const; + Addressee &operator*(); + Addressee* operator->(); + Iterator &operator++(); + Iterator &operator++(int); + Iterator &operator--(); + Iterator &operator--(int); + bool operator==( const Iterator &it ); + bool operator!=( const Iterator &it ); + + struct IteratorData; + IteratorData *d; + }; + + /** + @short Address Book Const Iterator + + This class provides a const iterator for address book entries. + */ + class ConstIterator + { + public: + ConstIterator(); + ConstIterator( const ConstIterator & ); + ~ConstIterator(); + + ConstIterator &operator=( const ConstIterator & ); + const Addressee &operator*() const; + const Addressee* operator->() const; + ConstIterator &operator++(); + ConstIterator &operator++(int); + ConstIterator &operator--(); + ConstIterator &operator--(int); + bool operator==( const ConstIterator &it ); + bool operator!=( const ConstIterator &it ); + + struct ConstIteratorData; + ConstIteratorData *d; + }; + + /** + Constructs a address book object. + + @param format File format class. + */ + AddressBook(); + AddressBook( const QString &config ); + virtual ~AddressBook(); + + /** + Requests a ticket for saving the addressbook. Calling this function locks + the addressbook for all other processes. If the address book is already + locked the function returns 0. You need the returned @ref Ticket object + for calling the @ref save() function. + + @see save() + */ + Ticket *requestSaveTicket( Resource *resource=0 ); + + /** + Load address book from file. + */ + bool load(); + + /** + Save address book. The address book is saved to the file, the Ticket + object has been requested for by @ref requestSaveTicket(). + + @param ticket a ticket object returned by @ref requestSaveTicket() + */ + bool save( Ticket *ticket ); + + /** + Returns a iterator for first entry of address book. + */ + Iterator begin(); + + /** + Returns a const iterator for first entry of address book. + */ + ConstIterator begin() const; + + /** + Returns a iterator for first entry of address book. + */ + Iterator end(); + + /** + Returns a const iterator for first entry of address book. + */ + ConstIterator end() const; + + /** + Removes all entries from address book. + */ + void clear(); + + /** + Insert an Addressee object into address book. If an object with the same + unique id already exists in the address book it it replaced by the new + one. If not the new object is appended to the address book. + */ + void insertAddressee( const Addressee & ); + + /** + Removes entry from the address book. + */ + void removeAddressee( const Addressee & ); + + /** + This is like @ref removeAddressee() just above, with the difference that + the first element is a iterator, returned by @ref begin(). + */ + void removeAddressee( const Iterator & ); + + /** + Find the specified entry in address book. Returns end(), if the entry + couldn't be found. + */ + Iterator find( const Addressee & ); + + /** + Find the entry specified by an unique id. Returns an empty Addressee + object, if the address book does not contain an entry with this id. + */ + Addressee findByUid( const QString & ); + + + /** + Returns a list of all addressees in the address book. This list can + be sorted with @ref KABC::AddresseeList for example. + */ + Addressee::List allAddressees(); + + /** + Find all entries with the specified name in the address book. Returns + an empty list, if no entries could be found. + */ + Addressee::List findByName( const QString & ); + + /** + Find all entries with the specified email address in the address book. + Returns an empty list, if no entries could be found. + */ + Addressee::List findByEmail( const QString & ); + + /** + Find all entries wich have the specified category in the address book. + Returns an empty list, if no entries could be found. + */ + Addressee::List findByCategory( const QString & ); + + /** + Return a string identifying this addressbook. + */ + virtual QString identifier(); + + /** + Used for debug output. + */ + void dump() const; + + void emitAddressBookLocked() { emit addressBookLocked( this ); } + void emitAddressBookUnlocked() { emit addressBookUnlocked( this ); } + void emitAddressBookChanged() { emit addressBookChanged( this ); } + + /** + Return list of all Fields known to the address book which are associated + with the given field category. + */ + Field::List fields( int category = Field::All ); + + /** + Add custom field to address book. + + @param label User visible label of the field. + @param category Ored list of field categories. + @param key Identifier used as key for reading and writing the field. + @param app String used as application key for reading and writing + the field. + */ + bool addCustomField( const QString &label, int category = Field::All, + const QString &key = QString::null, + const QString &app = QString::null ); + + + /** + Add address book resource. + */ + bool addResource( Resource * ); + + /** + Remove address book resource. + */ + bool removeResource( Resource * ); + + /** + Return pointer list of all resources. + */ + QPtrList<Resource> resources(); + + /** + Set the @p ErrorHandler, that is used by @ref error() to + provide gui-independend error messages. + */ + void setErrorHandler( ErrorHandler * ); + + /** + Shows gui independend error messages. + */ + void error( const QString& ); + + /** + Query all resources to clean up their lock files + */ + void cleanUp(); + + signals: + /** + Emitted, when the address book has changed on disk. + */ + void addressBookChanged( AddressBook * ); + + /** + Emitted, when the address book has been locked for writing. + */ + void addressBookLocked( AddressBook * ); + + /** + Emitted, when the address book has been unlocked. + */ + void addressBookUnlocked( AddressBook * ); + + protected: + void deleteRemovedAddressees(); + void setStandardResource( Resource * ); + Resource *standardResource(); + KRES::Manager<Resource> *resourceManager(); + + private: +#ifndef KAB_EMBEDDED + QPtrList<Resource> mDummy; // Remove in KDE 4 +#endif //KAB_EMBEDDED + +#ifdef KAB_EMBEDDED +//US optimization + void init(const QString &config); +#endif //KAB_EMBEDDED + + + struct AddressBookData; + AddressBookData *d; +}; + +QDataStream &operator<<( QDataStream &, const AddressBook & ); +QDataStream &operator>>( QDataStream &, AddressBook & ); + +} + +#endif |