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/resource.h

320 lines
8.8 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_RESOURCE_H
#define KABC_RESOURCE_H
#include <tderesources/resource.h>
#include "addressbook.h"
#include "plugin.h"
namespace KABC {
/**
* @short Helper class for handling coordinated save of address books.
*
* This class is used as helper class for saving address book.
* @see requestSaveTicket(), save().
*/
class KABC_EXPORT Ticket
{
friend class Resource;
public:
~Ticket();
Resource *resource();
private:
Ticket( Resource *resource );
Resource *mResource;
};
/**
* @internal
*/
class KABC_EXPORT Resource : public KRES::Resource
{
Q_OBJECT
public:
/**
@short Resource Iterator
This class provides an iterator for resource entries.
By default it points to a TQValueList<Addressee>::Iterator,
but you can reimplement this class to fit your own needs.
*/
class KABC_EXPORT Iterator
{
public:
Iterator();
Iterator( const Iterator & );
virtual ~Iterator();
virtual Iterator &operator=( const Iterator & );
virtual const Addressee &operator*() const;
virtual Addressee &operator*();
virtual Iterator &operator++();
virtual Iterator &operator++( int );
virtual Iterator &operator--();
virtual Iterator &operator--( int );
virtual bool operator==( const Iterator &it );
virtual bool operator!=( const Iterator &it );
struct IteratorData;
IteratorData *d;
};
/**
@short Resource Const Iterator
This class provides a const iterator for resource entries.
*/
class KABC_EXPORT ConstIterator
{
public:
ConstIterator();
ConstIterator( const ConstIterator & );
ConstIterator( const Iterator & );
virtual ~ConstIterator();
virtual ConstIterator &operator=( const ConstIterator & );
virtual const Addressee &operator*() const ;
virtual ConstIterator &operator++();
virtual ConstIterator &operator++( int );
virtual ConstIterator &operator--();
virtual ConstIterator &operator--( int );
virtual bool operator==( const ConstIterator &it );
virtual bool operator!=( const ConstIterator &it );
struct ConstIteratorData;
ConstIteratorData *d;
};
/**
Constructor.
@param config The config object where the derived classes can
read out their settings.
*/
Resource( const TDEConfig *config );
/**
Destructor.
*/
virtual ~Resource();
/**
Returns an iterator pointing to the first addressee in the resource.
This iterator equals end() if the resource is empty.
*/
virtual ConstIterator begin() const;
/**
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
*/
virtual Iterator begin();
/**
Returns an iterator pointing to the last addressee in the resource.
This iterator equals begin() if the resource is empty.
*/
virtual ConstIterator end() const;
/**
This is an overloaded member function, provided for convenience. It
behaves essentially like the above function.
*/
virtual Iterator end();
/**
Returns a pointer to the addressbook.
*/
AddressBook *addressBook();
/**
Writes the resource specific config to file.
*/
virtual void writeConfig( TDEConfig *config );
/**
Request a ticket, you have to pass through save() to
allow locking. The resource has to create its locks
in this function.
*/
virtual Ticket *requestSaveTicket() = 0;
/**
Releases the ticket previousely requested with requestSaveTicket().
The resource has to remove its locks in this function.
This function is also responsible for deleting the ticket.
*/
virtual void releaseSaveTicket( Ticket* ) = 0;
/**
Loads all addressees synchronously.
@returns Whether the loading was successfully.
*/
virtual bool load() = 0;
/**
Loads all addressees asyncronously. You have to make sure that either
the loadingFinished() or loadingError() signal is emitted from within
this function.
The default implementation simply calls the synchronous load.
@return Whether the synchronous part of loading was successfully.
*/
virtual bool asyncLoad();
/**
Insert an addressee into the resource.
*/
virtual void insertAddressee( const Addressee& );
/**
Removes an addressee from resource.
*/
virtual void removeAddressee( const Addressee& addr );
/**
Saves all addressees synchronously.
@param ticket You have to release the ticket later with
releaseSaveTicket() explicitely.
@return Whether the saving was successfully.
*/
virtual bool save( Ticket *ticket ) = 0;
/**
Saves all addressees asynchronously. You have to make sure that either
the savingFinished() or savingError() signal is emitted from within
this function.
The default implementation simply calls the synchronous save.
@param ticket You have to release the ticket later with
releaseSaveTicket() explicitely.
@return Whether the saving was successfully.
*/
virtual bool asyncSave( Ticket *ticket );
/**
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.
*/
virtual Addressee findByUid( const TQString &uid );
/**
Searches all addressees which match the specified name.
@param name The name you are looking for.
@return A list of all matching addressees.
*/
virtual Addressee::List findByName( const TQString &name );
/**
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.
*/
virtual Addressee::List findByEmail( const TQString &email );
/**
Searches all addressees which belongs to the specified category.
@param category The category you are looking for.
@return A list of all matching addressees.
*/
virtual Addressee::List findByCategory( const TQString &category );
/**
Removes all addressees from the resource.
*/
virtual void clear();
/**
@internal
Sets the address book of the resource.
*/
void setAddressBook( AddressBook* );
signals:
/**
This signal is emitted when the resource has finished the loading of all
addressees from the backend to the internal cache.
@param resource The pointer to the resource which emitted this signal.
*/
void loadingFinished( Resource *resource );
/**
This signal is emitted when an error occured during loading the
addressees from the backend to the internal cache.
@param resource The pointer to the resource which emitted this signal.
@param msg A translated error message.
*/
void loadingError( Resource *resource, const TQString &msg );
/**
This signal is emitted when the resource has finished the saving of all
addressees from the internal cache to the backend.
@param resource The pointer to the resource which emitted this signal.
*/
void savingFinished( Resource *resource );
/**
This signal is emitted when an error occured during saving the
addressees from the internal cache to the backend.
@param resource The pointer to the resource which emitted this signal.
@param msg A translated error message.
*/
void savingError( Resource *resource, const TQString &msg );
protected:
Ticket *createTicket( Resource * );
Addressee::Map mAddrMap;
private:
AddressBook *mAddressBook;
class ResourcePrivate;
ResourcePrivate *d;
};
}
#endif