addressbook.h

00001 /*
00002     This file is part of libkabc.
00003     Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
00004 
00005     This library is free software; you can redistribute it and/or
00006     modify it under the terms of the GNU Library General Public
00007     License as published by the Free Software Foundation; either
00008     version 2 of the License, or (at your option) any later version.
00009 
00010     This library is distributed in the hope that it will be useful,
00011     but WITHOUT ANY WARRANTY; without even the implied warranty of
00012     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013     Library General Public License for more details.
00014 
00015     You should have received a copy of the GNU Library General Public License
00016     along with this library; see the file COPYING.LIB.  If not, write to
00017     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
00018     Boston, MA 02110-1301, USA.
00019 */
00020 
00021 #ifndef KABC_ADDRESSBOOK_H
00022 #define KABC_ADDRESSBOOK_H
00023 
00024 #include <qobject.h>
00025 #include <qptrlist.h>
00026 
00027 #include <kresources/manager.h>
00028 
00029 #include "addressee.h"
00030 #include "field.h"
00031 
00032 namespace KABC {
00033 
00034 class ErrorHandler;
00035 class Resource;
00036 class Ticket;
00037 
00043 class KABC_EXPORT AddressBook : public QObject
00044 {
00045   Q_OBJECT
00046 
00047   friend KABC_EXPORT QDataStream &operator<<( QDataStream &, const AddressBook & );
00048   friend KABC_EXPORT QDataStream &operator>>( QDataStream &, AddressBook & );
00049   friend class StdAddressBook;
00050 
00051   public:
00057     class KABC_EXPORT Iterator
00058     {
00059       public:
00060         Iterator();
00061         Iterator( const Iterator & );
00062         ~Iterator();
00063 
00064         Iterator &operator=( const Iterator & );
00065         const Addressee &operator*() const;
00066         Addressee &operator*();
00067         Addressee* operator->();
00068         Iterator &operator++();
00069         Iterator &operator++(int);
00070         Iterator &operator--();
00071         Iterator &operator--(int);
00072         bool operator==( const Iterator &it );
00073         bool operator!=( const Iterator &it );
00074 
00075         struct IteratorData;
00076         IteratorData *d;
00077     };
00078 
00084     class KABC_EXPORT ConstIterator
00085     {
00086       public:
00087         ConstIterator();
00088         ConstIterator( const ConstIterator & );
00089         ConstIterator( const Iterator & );
00090         ~ConstIterator();
00091 
00092         ConstIterator &operator=( const ConstIterator & );
00093         const Addressee &operator*() const;
00094         const Addressee* operator->() const;
00095         ConstIterator &operator++();
00096         ConstIterator &operator++(int);
00097         ConstIterator &operator--();
00098         ConstIterator &operator--(int);
00099         bool operator==( const ConstIterator &it );
00100         bool operator!=( const ConstIterator &it );
00101 
00102         struct ConstIteratorData;
00103         ConstIteratorData *d;
00104     };
00105 
00110     AddressBook();
00111 
00118     AddressBook( const QString &config );
00119 
00123     virtual ~AddressBook();
00124 
00136     Ticket *requestSaveTicket( Resource *resource = 0 );
00137 
00142     void releaseSaveTicket( Ticket *ticket );
00143 
00149     bool load();
00150 
00158     bool asyncLoad();
00159 
00167     bool save( Ticket *ticket );
00168 
00176     bool asyncSave( Ticket *ticket );
00177 
00182     ConstIterator begin() const;
00183 
00188     Iterator begin();
00189 
00194     ConstIterator end() const;
00195 
00200     Iterator end();
00201 
00202 
00206     void clear();
00207 
00215     void insertAddressee( const Addressee &addr );
00216 
00222     void removeAddressee( const Addressee &addr );
00223 
00230     void removeAddressee( const Iterator &it );
00231 
00238     Iterator find( const Addressee &addr ); // KDE4: const
00239 
00247     Addressee findByUid( const QString &uid ); // KDE4: const
00248 
00252     Addressee::List allAddressees(); // KDE4: const
00253 
00260     Addressee::List findByName( const QString &name ); // KDE4: const
00261 
00268     Addressee::List findByEmail( const QString &email ); // KDE4: const
00269 
00276     Addressee::List findByCategory( const QString &category ); // KDE4: const
00277 
00282     virtual QString identifier(); // KDE4: const
00283 
00288     Field::List fields( int category = Field::All ); // KDE4: const
00289 
00299     bool addCustomField( const QString &label, int category = Field::All,
00300                          const QString &key = QString::null,
00301                          const QString &app = QString::null );
00302 
00309     bool addResource( Resource *resource );
00310 
00317     bool removeResource( Resource *resource );
00318 
00322     QPtrList<Resource> resources(); // KDE4: const
00323 
00330     void setErrorHandler( ErrorHandler *errorHandler );
00331 
00337     void error( const QString &msg );
00338 
00342     void cleanUp() KDE_DEPRECATED;
00343 
00348     void dump() const;
00349 
00352     void emitAddressBookLocked() { emit addressBookLocked( this ); }
00353     void emitAddressBookUnlocked() { emit addressBookUnlocked( this ); }
00354     void emitAddressBookChanged() { emit addressBookChanged( this ); }
00355 
00362     bool loadingHasFinished() const;
00363 
00364   signals:
00373     void addressBookChanged( AddressBook *addressBook );
00374 
00380     void addressBookLocked( AddressBook *addressBook );
00381 
00390     void addressBookUnlocked( AddressBook *addressBook );
00391 
00398     void loadingFinished( Resource *resource );
00399 
00406     void savingFinished( Resource *resource );
00407 
00408   protected slots:
00409     void resourceLoadingFinished( Resource* );
00410     void resourceSavingFinished( Resource* );
00411     void resourceLoadingError( Resource*, const QString& );
00412     void resourceSavingError( Resource*, const QString& );
00413 
00414   protected:
00415     void deleteRemovedAddressees();
00416     void setStandardResource( Resource* );
00417     Resource *standardResource();
00418     KRES::Manager<Resource> *resourceManager();
00419 
00420   private:
00421     QPtrList<Resource> mDummy; // Remove in KDE 4
00422     struct AddressBookData;
00423     AddressBookData *d;
00424 };
00425 
00426 KABC_EXPORT QDataStream &operator<<( QDataStream &, const AddressBook & );
00427 KABC_EXPORT QDataStream &operator>>( QDataStream &, AddressBook & );
00428 
00429 }
00430 
00431 #endif
KDE Home | KDE Accessibility Home | Description of Access Keys