home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kabc / resource.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  8.8 KB  |  320 lines
  1. /*
  2.     This file is part of libkabc.
  3.     Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
  4.  
  5.     This library is free software; you can redistribute it and/or
  6.     modify it under the terms of the GNU Library General Public
  7.     License as published by the Free Software Foundation; either
  8.     version 2 of the License, or (at your option) any later version.
  9.  
  10.     This library is distributed in the hope that it will be useful,
  11.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.     Library General Public License for more details.
  14.  
  15.     You should have received a copy of the GNU Library General Public License
  16.     along with this library; see the file COPYING.LIB.  If not, write to
  17.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.     Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef KABC_RESOURCE_H
  22. #define KABC_RESOURCE_H
  23.  
  24. #include <kresources/resource.h>
  25.  
  26. #include "addressbook.h"
  27. #include "plugin.h"
  28.  
  29. namespace KABC {
  30.  
  31. /**
  32.  * @short Helper class for handling coordinated save of address books.
  33.  *
  34.  * This class is used as helper class for saving address book.
  35.  * @see requestSaveTicket(), save().
  36.  */
  37. class KABC_EXPORT Ticket
  38. {
  39.     friend class Resource;
  40.  
  41.   public:
  42.     ~Ticket();
  43.  
  44.     Resource *resource();
  45.  
  46.   private:
  47.     Ticket( Resource *resource );
  48.  
  49.     Resource *mResource;
  50. };
  51.  
  52. /**
  53.  * @internal
  54.  */
  55. class KABC_EXPORT Resource : public KRES::Resource
  56. {
  57.   Q_OBJECT
  58.  
  59.   public:
  60.  
  61.     /**
  62.       @short Resource Iterator
  63.  
  64.       This class provides an iterator for resource entries.
  65.       By default it points to a QValueList<Addressee>::Iterator,
  66.       but you can reimplement this class to fit your own needs.
  67.     */
  68.     class KABC_EXPORT Iterator
  69.     {
  70.       public:
  71.         Iterator();
  72.         Iterator( const Iterator & );
  73.         virtual ~Iterator();
  74.  
  75.         virtual Iterator &operator=( const Iterator & );
  76.         virtual const Addressee &operator*() const;
  77.         virtual Addressee &operator*();
  78.         virtual Iterator &operator++();
  79.         virtual Iterator &operator++( int );
  80.         virtual Iterator &operator--();
  81.         virtual Iterator &operator--( int );
  82.         virtual bool operator==( const Iterator &it );
  83.         virtual bool operator!=( const Iterator &it );
  84.  
  85.         struct IteratorData;
  86.         IteratorData *d;
  87.     };
  88.  
  89.     /**
  90.       @short Resource Const Iterator
  91.  
  92.       This class provides a const iterator for resource entries.
  93.     */
  94.     class KABC_EXPORT ConstIterator
  95.     {
  96.       public:
  97.         ConstIterator();
  98.         ConstIterator( const ConstIterator & );
  99.         ConstIterator( const Iterator & );
  100.         virtual ~ConstIterator();
  101.  
  102.         virtual ConstIterator &operator=( const ConstIterator & );
  103.         virtual const Addressee &operator*() const ;
  104.         virtual ConstIterator &operator++();
  105.         virtual ConstIterator &operator++( int );
  106.         virtual ConstIterator &operator--();
  107.         virtual ConstIterator &operator--( int );
  108.         virtual bool operator==( const ConstIterator &it );
  109.         virtual bool operator!=( const ConstIterator &it );
  110.  
  111.         struct ConstIteratorData;
  112.         ConstIteratorData *d;
  113.     };
  114.  
  115.     /**
  116.       Constructor.
  117.  
  118.       @param config The config object where the derived classes can
  119.                     read out their settings.
  120.      */
  121.     Resource( const KConfig *config );
  122.  
  123.     /**
  124.       Destructor.
  125.      */
  126.     virtual ~Resource();
  127.  
  128.     /**
  129.       Returns an iterator pointing to the first addressee in the resource.
  130.       This iterator equals end() if the resource is empty.
  131.      */
  132.     virtual ConstIterator begin() const;
  133.  
  134.     /**
  135.       This is an overloaded member function, provided for convenience. It
  136.       behaves essentially like the above function.
  137.      */
  138.     virtual Iterator begin();
  139.  
  140.     /**
  141.       Returns an iterator pointing to the last addressee in the resource.
  142.       This iterator equals begin() if the resource is empty.
  143.      */
  144.     virtual ConstIterator end() const;
  145.  
  146.     /**
  147.       This is an overloaded member function, provided for convenience. It
  148.       behaves essentially like the above function.
  149.      */
  150.     virtual Iterator end();
  151.  
  152.     /**
  153.       Returns a pointer to the addressbook.
  154.      */
  155.     AddressBook *addressBook();
  156.  
  157.     /**
  158.       Writes the resource specific config to file.
  159.      */
  160.     virtual void writeConfig( KConfig *config );
  161.  
  162.     /**
  163.       Request a ticket, you have to pass through save() to
  164.       allow locking. The resource has to create its locks
  165.       in this function.
  166.     */
  167.     virtual Ticket *requestSaveTicket() = 0;
  168.  
  169.     /**
  170.       Releases the ticket previousely requested with requestSaveTicket().
  171.       The resource has to remove its locks in this function.
  172.       This function is also responsible for deleting the ticket.
  173.      */
  174.     virtual void releaseSaveTicket( Ticket* ) = 0;
  175.  
  176.     /**
  177.       Loads all addressees synchronously.
  178.  
  179.       @returns Whether the loading was successfully.
  180.      */
  181.     virtual bool load() = 0;
  182.  
  183.     /**
  184.       Loads all addressees asyncronously. You have to make sure that either
  185.       the loadingFinished() or loadingError() signal is emitted from within
  186.       this function.
  187.  
  188.       The default implementation simply calls the synchronous load.
  189.  
  190.       @return Whether the synchronous part of loading was successfully.
  191.      */
  192.     virtual bool asyncLoad();
  193.  
  194.     /**
  195.       Insert an addressee into the resource.
  196.      */
  197.     virtual void insertAddressee( const Addressee& );
  198.  
  199.     /**
  200.       Removes an addressee from resource.
  201.      */
  202.     virtual void removeAddressee( const Addressee& addr );
  203.  
  204.     /**
  205.       Saves all addressees synchronously.
  206.  
  207.       @param ticket You have to release the ticket later with
  208.                     releaseSaveTicket() explicitely.
  209.       @return Whether the saving was successfully.
  210.      */
  211.     virtual bool save( Ticket *ticket ) = 0;
  212.  
  213.     /**
  214.       Saves all addressees asynchronously. You have to make sure that either
  215.       the savingFinished() or savingError() signal is emitted from within
  216.       this function.
  217.  
  218.       The default implementation simply calls the synchronous save.
  219.  
  220.       @param ticket You have to release the ticket later with
  221.                     releaseSaveTicket() explicitely.
  222.       @return Whether the saving was successfully.
  223.      */
  224.     virtual bool asyncSave( Ticket *ticket );
  225.  
  226.     /**
  227.       Searches an addressee with the specified unique identifier.
  228.  
  229.       @param uid The unique identifier you are looking for.
  230.       @return The addressee with the specified unique identifier or an
  231.               empty addressee.
  232.      */
  233.     virtual Addressee findByUid( const QString &uid );
  234.  
  235.     /**
  236.       Searches all addressees which match the specified name.
  237.  
  238.       @param name The name you are looking for.
  239.       @return A list of all matching addressees.
  240.      */
  241.     virtual Addressee::List findByName( const QString &name );
  242.  
  243.     /**
  244.       Searches all addressees which match the specified email address.
  245.  
  246.       @param email The email address you are looking for.
  247.       @return A list of all matching addressees.
  248.      */
  249.     virtual Addressee::List findByEmail( const QString &email );
  250.  
  251.     /**
  252.       Searches all addressees which belongs to the specified category.
  253.  
  254.       @param category The category you are looking for.
  255.       @return A list of all matching addressees.
  256.      */
  257.     virtual Addressee::List findByCategory( const QString &category );
  258.  
  259.     /**
  260.       Removes all addressees from the resource.
  261.      */
  262.     virtual void clear();
  263.  
  264.     /**
  265.       @internal
  266.  
  267.       Sets the address book of the resource.
  268.      */
  269.     void setAddressBook( AddressBook* );
  270.  
  271.   signals:
  272.     /**
  273.       This signal is emitted when the resource has finished the loading of all
  274.       addressees from the backend to the internal cache.
  275.  
  276.       @param resource The pointer to the resource which emitted this signal.
  277.      */
  278.     void loadingFinished( Resource *resource );
  279.  
  280.     /**
  281.       This signal is emitted when an error occured during loading the
  282.       addressees from the backend to the internal cache.
  283.  
  284.       @param resource The pointer to the resource which emitted this signal.
  285.       @param msg A translated error message.
  286.      */
  287.     void loadingError( Resource *resource, const QString &msg );
  288.  
  289.     /**
  290.       This signal is emitted when the resource has finished the saving of all
  291.       addressees from the internal cache to the backend.
  292.  
  293.       @param resource The pointer to the resource which emitted this signal.
  294.      */
  295.     void savingFinished( Resource *resource );
  296.  
  297.     /**
  298.       This signal is emitted when an error occured during saving the
  299.       addressees from the internal cache to the backend.
  300.  
  301.       @param resource The pointer to the resource which emitted this signal.
  302.       @param msg A translated error message.
  303.      */
  304.     void savingError( Resource *resource, const QString &msg );
  305.  
  306.   protected:
  307.     Ticket *createTicket( Resource * );
  308.     Addressee::Map mAddrMap;
  309.  
  310.   private:
  311.     AddressBook *mAddressBook;
  312.  
  313.     class ResourcePrivate;
  314.     ResourcePrivate *d;
  315. };
  316.  
  317. }
  318.  
  319. #endif
  320.