kaddressbook/recursiveitemfetchjob.h

   1 /*
   2     Copyright (c) 2009 Tobias Koenig <tokoe@kde.org>
   3
   4     This library is free software; you can redistribute it and/or modify it
   5     under the terms of the GNU Library General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or (at your
   7     option) any later version.
   8
   9     This library is distributed in the hope that it will be useful, but WITHOUT
  10     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  12     License for more details.
  13
  14     You should have received a copy of the GNU Library General Public License
  15     along with this library; see the file COPYING.LIB.  If not, write to the
  16     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17     02110-1301, USA.
  18 */
  19
  20 #ifndef AKONADI_RECURSIVEITEMFETCHJOB_H
  21 #define AKONADI_RECURSIVEITEMFETCHJOB_H
  22
  23 #include <akonadi/item.h>
  24 #include <kjob.h>
  25
  26 namespace Akonadi {
  27
  28 class Collection;
  29 class ItemFetchScope;
  30
  31 /**
  32  * @short Job that fetches all items of a collection recursive.
  33  *
  34  * This job takes a collection as argument and returns a list of
  35  * all items that are part of the passed collection and its child
  36  * collections. The parts of the items that shall be fetched can
  37  * by specified via an ItemFetchScope.
  38  *
  39  * Example:
  40  *
  41  * @code
  42  *
  43  * // Assume the following Akonadi storage tree structure:
  44  * //
  45  * // Root Collection
  46  * // |
  47  * // +- Contacts
  48  * // |  |
  49  * // |  +- Private
  50  * // |  |
  51  * // |  `- Business
  52  * // |
  53  * // `- Events
  54  * //
  55  * // Collection 'Contacts' has the ID 15, then the following code
  56  * // returns all items from 'Contacts', 'Private' and 'Business'.
  57  *
  58  * const Akonadi::Collection contactsCollection( 15 );
  59  *
  60  * Akonadi::RecursiveItemFetchJob *job = new Akonadi::RecursiveItemFetchJob( contactsCollection );
  61  * job->fetchScope().fetchFullPayload();
  62  * connect( job, SIGNAL( result( KJob* ) ), this, SLOT( fetchResult( KJob* ) ) );
  63  *
  64  * job->start();
  65  *
  66  * ...
  67  *
  68  * MyClass::fetchResult( KJob *job )
  69  * {
  70  *   Akonadi::RecursiveItemFetchJob *fetchJob = qobject_cast<Akonadi::RecursiveItemFetchJob*>( job );
  71  *   const Akonadi::Item::List items = fetchJob->items();
  72  *   // do something with the items
  73  * }
  74  *
  75  * @endcode
  76  *
  77  * @author Tobias Koenig <tokoe@kde.org>
  78  */
  79 class RecursiveItemFetchJob : public KJob
  80 {
  81   Q_OBJECT
  82
  83   public:
  84     /**
  85      * Creates a new recursive item fetch job.
  86      *
  87      * @param collection The collection that shall be fetched recursive.
  88      * @param parent The parent object.
  89      */
  90     explicit RecursiveItemFetchJob( const Akonadi::Collection &collection, QObject *parent = 0 );
  91
  92     /**
  93      * Destroys the recursive item fetch job.
  94      */
  95     ~RecursiveItemFetchJob();
  96
  97     /**
  98      * Sets the item fetch scope.
  99      *
 100      * The ItemFetchScope controls how much of an item's data is fetched
 101      * from the server, e.g. whether to fetch the full item payload or
 102      * only meta data.
 103      *
 104      * @param fetchScope The new scope for item fetch operations.
 105      *
 106      * @see fetchScope()
 107      */
 108     void setFetchScope( const Akonadi::ItemFetchScope &fetchScope );
 109
 110     /**
 111      * Returns the item fetch scope.
 112      *
 113      * Since this returns a reference it can be used to conveniently modify the
 114      * current scope in-place, i.e. by calling a method on the returned reference
 115      * without storing it in a local variable. See the ItemFetchScope documentation
 116      * for an example.
 117      *
 118      * @return a reference to the current item fetch scope
 119      *
 120      * @see setFetchScope() for replacing the current item fetch scope
 121      */
 122     Akonadi::ItemFetchScope &fetchScope();
 123
 124     /**
 125      * Returns the list of fetched items.
 126      */
 127     Akonadi::Item::List items() const;
 128
 129     /**
 130      * Starts the recursive item fetch job.
 131      */
 132     virtual void start();
 133
 134   private:
 135     //@cond PRIVATE
 136     class Private;
 137     Private* const d;
 138
 139     Q_PRIVATE_SLOT( d, void collectionFetchResult( KJob* ) )
 140     Q_PRIVATE_SLOT( d, void itemFetchResult( KJob* ) )
 141     //@endcond
 142 };
 143
 144 }
 145
 146 #endif