1 files changed, 431 insertions, 0 deletions
diff --git a/tdeabc/addressbook.h b/tdeabc/addressbook.h
new file mode 100644
index 000000000..8b87b6898
--- /dev/null
+++ b/tdeabc/addressbook.h
@@ -0,0 +1,431 @@
+/*
+    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., 51 Franklin Street, Fifth Floor,
+    Boston, MA 02110-1301, USA.
+*/
+
+#ifndef KABC_ADDRESSBOOK_H
+#define KABC_ADDRESSBOOK_H
+
+#include <tqobject.h>
+#include <tqptrlist.h>
+
+#include <tderesources/manager.h>
+
+#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 KABC_EXPORT AddressBook : public TQObject
+{
+  Q_OBJECT
+
+  friend KABC_EXPORT TQDataStream &operator<<( TQDataStream &, const AddressBook & );
+  friend KABC_EXPORT TQDataStream &operator>>( TQDataStream &, AddressBook & );
+  friend class StdAddressBook;
+
+  public:
+    /**
+      @short Address Book Iterator
+
+      This class provides an iterator for address book entries.
+     */
+    class KABC_EXPORT 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 KABC_EXPORT ConstIterator
+    {
+      public:
+        ConstIterator();
+        ConstIterator( const ConstIterator & );
+        ConstIterator( const Iterator & );
+        ~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 an address book object.
+      You have to add the resources manually before calling load().
+     */
+    AddressBook();
+
+    /**
+      Constructs an address book object.
+      The resources are loaded automatically.
+
+      @param config The config file which contains the resource settings.
+     */
+    AddressBook( const TQString &config );
+
+    /**
+      Destructor.
+     */
+    virtual ~AddressBook();
+
+    /**
+      Requests a ticket for saving the addressbook. Calling this function locks
+      the addressbook for all other processes. You need the returned ticket
+      object for calling the save() function.
+
+      @param resource A pointer to the resource which shall be locked. If 0,
+                      the default resource is locked.
+      @return 0 if the resource is already locked or a valid save ticket
+              otherwise.
+      @see save()
+     */
+    Ticket *requestSaveTicket( Resource *resource = 0 );
+
+    /**
+      Releases the ticket requested previously with requestSaveTicket().
+      Call this function, if you want to release a ticket without saving.
+     */
+    void releaseSaveTicket( Ticket *ticket );
+
+    /**
+      Loads all addressees synchronously.
+
+      @return Whether the loading was successfully.
+     */
+    bool load();
+
+    /**
+      Loads all addressees asynchronously. This function returns immediately
+      and emits the addressBookChanged() signal as soon as the loading has
+      finished.
+
+      @return Whether the synchronous part of loading was successfully.
+     */
+    bool asyncLoad();
+
+    /**
+      Saves all addressees of one resource synchronously. If the save is
+      successfull the ticket is deleted.
+
+      @param ticket The ticket returned by requestSaveTicket().
+      @return Whether the saving was successfully.
+     */
+    bool save( Ticket *ticket );
+
+    /**
+      Saves all addressees of one resource asynchronously. If the save is
+      successfull the ticket is deleted.
+
+      @param ticket The ticket returned by requestSaveTicket().
+      @return Whether the synchronous part of saving was successfully.
+     */
+    bool asyncSave( Ticket *ticket );
+
+    /**
+      Returns an iterator pointing to the first addressee of address book.
+      This iterator equals end() if the address book is empty.
+     */
+    ConstIterator begin() const;
+
+    /**
+      This is an overloaded member function, provided for convenience. It
+      behaves essentially like the above function.
+     */
+    Iterator begin();
+
+    /**
+      Returns an iterator pointing to the last addressee of address book.
+      This iterator equals begin() if the address book is empty.
+     */
+    ConstIterator end() const;
+
+    /**
+      This is an overloaded member function, provided for convenience. It
+      behaves essentially like the above function.
+     */
+    Iterator end();
+
+
+    /**
+      Removes all addressees from the address book.
+     */
+    void clear();
+
+    /**
+      Insert an addressee into the address book. If an addressee with the same
+      unique id already exists, it is replaced by the new one, otherwise it is
+      appended.
+
+      @param addr The addressee which shall be insert.
+     */
+    void insertAddressee( const Addressee &addr );
+
+    /**
+      Removes an addressee from the address book.
+
+      @param addr The addressee which shall be removed.
+     */
+    void removeAddressee( const Addressee &addr );
+
+    /**
+      This is an overloaded member function, provided for convenience. It
+      behaves essentially like the above function.
+
+      @param it An iterator pointing to the addressee which shall be removed.
+     */
+    void removeAddressee( const Iterator &it );
+
+    /**
+      Returns an iterator pointing to the specified addressee. It will return
+      end() if no addressee matched.
+
+      @param addr The addresee you are looking for.
+     */
+    Iterator find( const Addressee &addr ); // KDE4: const
+
+    /**
+      Searches an addressee with the specified unique identifier.
+
+      @param uid The unique identifier you are looking for.
+      @return The addressee with the specified unique identifier or an
+              empty addressee.
+     */
+    Addressee findByUid( const TQString &uid ); // KDE4: const
+
+    /**
+      Returns a list of all addressees in the address book.
+     */
+    Addressee::List allAddressees(); // KDE4: const
+
+    /**
+      Searches all addressees which match the specified name.
+
+      @param name The name you are looking for.
+      @return A list of all matching addressees.
+     */
+    Addressee::List findByName( const TQString &name ); // KDE4: const
+
+    /**
+      Searches all addressees which match the specified email address.
+
+      @param email The email address you are looking for.
+      @return A list of all matching addressees.
+     */
+    Addressee::List findByEmail( const TQString &email ); // KDE4: const
+
+    /**
+      Searches all addressees which belongs to the specified category.
+
+      @param category The category you are looking for.
+      @return A list of all matching addressees.
+     */
+    Addressee::List findByCategory( const TQString &category ); // KDE4: const
+
+    /**
+      Returns a string identifying this addressbook. The identifier is
+      created by concatenation of the resource identifiers.
+     */
+    virtual TQString identifier(); // KDE4: const
+
+    /**
+      Returns a list of all Fields known to the address book which are associated
+      with the given field category.
+     */
+    Field::List fields( int category = Field::All ); // KDE4: const
+
+    /**
+      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 TQString &label, int category = Field::All,
+                         const TQString &key = TQString::null,
+                         const TQString &app = TQString::null );
+
+    /**
+      Adds a resource to the address book.
+
+      @param resource The resource you want to add.
+      @return Whether opening the resource was successfully.
+     */
+    bool addResource( Resource *resource );
+
+    /**
+      Removes a resource from the address book.
+
+      @param resource The resource you want to remove.
+      @return Whether closing the resource was successfully.
+     */
+    bool removeResource( Resource *resource );
+
+    /**
+      Returns a list of all resources.
+     */
+    TQPtrList<Resource> resources(); // KDE4: const
+
+    /**
+      Sets the @p ErrorHandler, that is used by error() to
+      provide GUI independent error messages.
+
+      @param errorHandler The error handler you want to use.
+     */
+    void setErrorHandler( ErrorHandler *errorHandler );
+
+    /**
+      Shows GUI independent error messages.
+
+      @param msg The error message that shall be displayed.
+     */
+    void error( const TQString &msg );
+
+    /**
+      @deprecated There is no need to call this function anymore.
+     */
+    void cleanUp() KDE_DEPRECATED;
+
+    /**
+      Used for debug output. This function prints out the list
+      of all addressees to kdDebug(5700).
+     */
+    void dump() const;
+
+    /**
+      */
+    void emitAddressBookLocked() { emit addressBookLocked( this ); }
+    void emitAddressBookUnlocked() { emit addressBookUnlocked( this ); }
+    void emitAddressBookChanged() { emit addressBookChanged( this ); }
+
+    /**
+      Returns true when the loading of the addressbook has finished,
+      otherwise false.
+
+      @since 3.5
+     */
+    bool loadingHasFinished() const;
+
+  signals:
+    /**
+      Emitted when one of the resources discovered a change in its backend
+      or the asynchronous loading of all resources has finished.
+      You should connect to this signal to update the presentation of
+      the contact data in your application.
+
+      @param addressBook The address book which emitted this signal.
+     */
+    void addressBookChanged( AddressBook *addressBook );
+
+    /**
+      Emitted when one of the resources has been locked for writing.
+
+      @param addressBook The address book which emitted this signal.
+     */
+    void addressBookLocked( AddressBook *addressBook );
+
+    /**
+      Emitted when one of the resources has been unlocked.
+      You should connect to this signal if you want to save your changes
+      to a resource which is currently locked, and want to get notified when
+      saving is possible again.
+
+      @param addressBook The address book which emitted this signal.
+     */
+    void addressBookUnlocked( AddressBook *addressBook );
+
+    /**
+      Emitted when the asynchronous loading of one resource has finished
+      after calling asyncLoad().
+
+      @param resource The resource which emitted this signal.
+     */
+    void loadingFinished( Resource *resource );
+
+    /**
+      Emitted when the asynchronous saving of one resource has finished
+      after calling asyncSave().
+
+      @param resource The resource which emitted this signal.
+     */
+    void savingFinished( Resource *resource );
+
+  protected slots:
+    void resourceLoadingFinished( Resource* );
+    void resourceSavingFinished( Resource* );
+    void resourceLoadingError( Resource*, const TQString& );
+    void resourceSavingError( Resource*, const TQString& );
+
+  protected:
+    void deleteRemovedAddressees();
+    void setStandardResource( Resource* );
+    Resource *standardResource();
+    KRES::Manager<Resource> *resourceManager();
+
+  private:
+    TQPtrList<Resource> mDummy; // Remove in KDE 4
+    struct AddressBookData;
+    AddressBookData *d;
+};
+
+KABC_EXPORT TQDataStream &operator<<( TQDataStream &, const AddressBook & );
+KABC_EXPORT TQDataStream &operator>>( TQDataStream &, AddressBook & );
+
+}
+
+#endif