From b9aad1f15dc600e4dbe4c62d3fcced6363188ba3 Mon Sep 17 00:00:00 2001 From: zautrix Date: Sat, 26 Jun 2004 19:01:18 +0000 Subject: Initial revision --- (limited to 'kabc/addressbook.h') 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 + + 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 + +#include +#include + +#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 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 *resourceManager(); + + private: +#ifndef KAB_EMBEDDED + QPtrList 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 -- cgit v0.9.0.2