Initial revision

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