From ce4a32fe52ef09d8f5ff1dd22c001110902b60a2 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- kabc/resource.h | 319 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 kabc/resource.h (limited to 'kabc/resource.h') diff --git a/kabc/resource.h b/kabc/resource.h new file mode 100644 index 000000000..556c3beae --- /dev/null +++ b/kabc/resource.h @@ -0,0 +1,319 @@ +/* + This file is part of libkabc. + Copyright (c) 2001 Cornelius Schumacher + + 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 + +#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 QValueList::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 KConfig *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( KConfig *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 QString &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 QString &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 QString &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 QString &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 QString &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 QString &msg ); + + protected: + Ticket *createTicket( Resource * ); + Addressee::Map mAddrMap; + + private: + AddressBook *mAddressBook; + + class ResourcePrivate; + ResourcePrivate *d; +}; + +} + +#endif -- cgit v1.2.1