You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdelibs/kabc/addressbook.h

432 lines
13 KiB

/*
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 <kresources/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 tqcontains 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 tqreplaced 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 tqfind( 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 tqfindByUid( 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 tqfindByName( 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 tqfindByEmail( 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 tqfindByCategory( 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