1/*
2 Copyright (c) 2009 Stephen Kelly <steveire@gmail.com>
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_PARTFETCHER_H
21#define AKONADI_PARTFETCHER_H
22
23#include <kjob.h>
24
25#include "akonadi_export.h"
26
27class QModelIndex;
28
29namespace Akonadi
30{
31
32class Item;
33class PartFetcherPrivate;
34
35/**
36 * @short Convenience class for getting payload parts from an Akonadi Model.
37 *
38 * This class can be used to retrieve individual payload parts from an EntityTreeModel,
39 * and fetch them asynchronously from the Akonadi storage if necessary.
40 *
41 * The requested part is emitted though the partFetched signal.
42 *
43 * Example:
44 *
45 * @code
46 *
47 * const QModelIndex index = view->selectionModel()->currentIndex();
48 *
49 * PartFetcher *fetcher = new PartFetcher( index, Akonadi::MessagePart::Envelope );
50 * connect( fetcher, SIGNAL(result(KJob*)), SLOT(fetchResult(KJob*)) );
51 * fetcher->start();
52 *
53 * ...
54 *
55 * MyClass::fetchResult( KJob *job )
56 * {
57 * if ( job->error() ) {
58 * qDebug() << job->errorText();
59 * return;
60 * }
61 *
62 * PartFetcher *fetcher = qobject_cast<PartFetcher*>( job );
63 *
64 * const Item item = fetcher->item();
65 * // do something with the item
66 * }
67 *
68 * @endcode
69 *
70 * @author Stephen Kelly <steveire@gmail.com>
71 * @since 4.4
72 */
73class AKONADI_EXPORT PartFetcher : public KJob
74{
75 Q_OBJECT
76
77public:
78 /**
79 * Creates a new part fetcher.
80 *
81 * @param index The index of the item to fetch the part from.
82 * @param partName The name of the payload part to fetch.
83 * @param parent The parent object.
84 */
85 PartFetcher(const QModelIndex &index, const QByteArray &partName, QObject *parent = 0);
86
87 /**
88 * Destroys the part fetcher.
89 */
90 virtual ~PartFetcher();
91
92 /**
93 * Starts the fetch operation.
94 */
95 virtual void start();
96
97 /**
98 * Returns the index of the item the part was fetched from.
99 */
100 QModelIndex index() const;
101
102 /**
103 * Returns the name of the part that has been fetched.
104 */
105 QByteArray partName() const;
106
107 /**
108 * Returns the item that contains the fetched payload part.
109 */
110 Item item() const;
111
112private:
113 //@cond PRIVATE
114 Q_DECLARE_PRIVATE(Akonadi::PartFetcher)
115 PartFetcherPrivate *const d_ptr;
116
117 Q_PRIVATE_SLOT(d_func(), void fetchJobDone(KJob *job))
118 //@endcond
119};
120
121}
122
123#endif
124