addressbook.h

/*
    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 "kabc_export.h"

#include "addressee.h"
#include "field.h"

#include "kresources/manager.h"

#include <QtCore/QObject>
#include <QtCore/QList>

namespace KABC {

class DistributionList;
class ErrorHandler;
class Resource;
class Ticket;

class KABC_DEPRECATED_EXPORT AddressBook : public QObject
{
  Q_OBJECT

  friend KABC_EXPORT QDataStream &operator<<( QDataStream &lhs,
                                              const AddressBook &rhs );
  friend KABC_EXPORT QDataStream &operator>>( QDataStream &lhs,
                                              AddressBook &rhs );
  friend class StdAddressBook;

  public:
    class ConstIterator;

    class KABC_DEPRECATED_EXPORT Iterator  //krazy:exclude=dpointer
    {
      friend class AddressBook;
      friend class ConstIterator;
      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 ) const;

        bool operator!=( const Iterator &it ) const;

      private:
        struct IteratorData;
        IteratorData *const d;
    };

    class KABC_DEPRECATED_EXPORT ConstIterator //krazy:exclude=dpointer
    {
      friend class AddressBook;
      public:
        ConstIterator();

        ConstIterator( const ConstIterator & );

#ifndef QT_STRICT_ITERATORS

        ConstIterator( const Iterator & );
#endif

        ~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 ) const;

        bool operator!=( const ConstIterator &it ) const;

      private:
        struct ConstIteratorData;
        ConstIteratorData *const d;
    };

    typedef Iterator iterator;

    typedef ConstIterator const_iterator;

    AddressBook();

    AddressBook( const QString &config );

    virtual ~AddressBook();

    Ticket *requestSaveTicket( Resource *resource = 0 );

    void releaseSaveTicket( Ticket *ticket );

    bool load();

    bool asyncLoad();

    bool save( Ticket *ticket );

    bool asyncSave( Ticket *ticket );

    ConstIterator begin() const;
    ConstIterator constBegin() const { return begin(); }

    Iterator begin();

    ConstIterator end() const;
    ConstIterator constEnd() const { return end(); }

    Iterator end();

    void clear();

    void insertAddressee( const Addressee &addr );

    void removeAddressee( const Addressee &addr );

    void removeAddressee( const Iterator &it );

    Iterator find( const Addressee &addr );

    ConstIterator find( const Addressee &addr ) const;

    Addressee findByUid( const QString &uid ) const;

    Addressee::List allAddressees() const;

    Addressee::List findByName( const QString &name ) const;

    Addressee::List findByEmail( const QString &email ) const;

    Addressee::List findByCategory( const QString &category ) const;

    DistributionList *createDistributionList( const QString &name, Resource *resource = 0 );

    void removeDistributionList( DistributionList *list );

    DistributionList *findDistributionListByIdentifier( const QString &identifier );

    DistributionList *findDistributionListByName(
      const QString &name,
      Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive );

    QList<DistributionList*> allDistributionLists();

    QStringList allDistributionListNames() const;

    virtual QString identifier() const;

    Field::List fields( int category = Field::All ) const;

    bool addCustomField( const QString &label, int category = Field::All,
                         const QString &key = QString(),
                         const QString &app = QString() ) const;

    bool addResource( Resource *resource );

    bool removeResource( Resource *resource );

    QList<Resource*> resources() const;

    void setErrorHandler( ErrorHandler *errorHandler );

    void error( const QString &msg );

    void dump() const;

    void emitAddressBookLocked() { addressBookLocked( this ); }
    void emitAddressBookUnlocked() { addressBookUnlocked( this ); }
    void emitAddressBookChanged() { addressBookChanged( this ); }

    bool loadingHasFinished() const;

  Q_SIGNALS:
    void addressBookChanged( AddressBook *addressBook );

    void addressBookLocked( AddressBook *addressBook );

    void addressBookUnlocked( AddressBook *addressBook );

    void loadingFinished( Resource *resource );

    void savingFinished( Resource *resource );

  protected Q_SLOTS:
    void resourceLoadingFinished( Resource *resource );

    void resourceSavingFinished( Resource *resource );

    void resourceLoadingError( Resource *resource, const QString &errMsg );

    void resourceSavingError( Resource *resource, const QString &errMsg );

  protected:
    void setStandardResource( Resource *resource );

    Resource *standardResource();

    KRES::Manager<Resource> *resourceManager();

  private:
    class Private;
    Private *const d;
};

KABC_EXPORT QDataStream &operator<<( QDataStream &lhs, const AddressBook &rhs );
KABC_EXPORT QDataStream &operator>>( QDataStream &lhs, AddressBook &rhs );

}

#endif