1 /*
2     This file is part of Akonadi Contact.
3 
4     SPDX-FileCopyrightText: 2009 Tobias Koenig <tokoe@kde.org>
5 
6     SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #pragma once
10 
11 #include "akonadi-contact_export.h"
12 
13 #include <KContacts/Addressee>
14 #include <KContacts/ContactGroup>
15 #include <KJob>
16 
17 #include <memory>
18 
19 namespace Akonadi
20 {
21 class ContactGroupExpandJobPrivate;
22 
23 /**
24  * @short Job that expands a ContactGroup to a list of contacts.
25  *
26  * This job takes a KContacts::ContactGroup object or a name of a contact group and
27  * expands it to a list of KContacts::Addressee objects by creating temporary KContacts::Addressee objects
28  * for the KContacts::ContactGroup::Data objects of the group and fetching the
29  * complete contacts from the Akonadi storage for the
30  * KContacts::ContactGroup::ContactReferences of the group.
31  *
32  * @code
33  *
34  * const KContacts::ContactGroup group = ...;
35  *
36  * Akonadi::ContactGroupExpandJob *job = new Akonadi::ContactGroupExpandJob( group );
37  * connect( job, SIGNAL(result(KJob*)), this, SLOT(expandResult(KJob*)) );
38  * job->start();
39  *
40  * ...
41  *
42  * MyClass::expandResult( KJob *job )
43  * {
44  *   Akonadi::ContactGroupExpandJob *expandJob = qobject_cast<Akonadi::ContactGroupExpandJob*>( job );
45  *   const KContacts::Addressee::List contacts = expandJob->contacts();
46  *   // do something with the contacts
47  * }
48  *
49  * @endcode
50  *
51  * @author Tobias Koenig <tokoe@kde.org>
52  * @since 4.4
53  */
54 class AKONADI_CONTACT_EXPORT ContactGroupExpandJob : public KJob
55 {
56     Q_OBJECT
57 
58 public:
59     /**
60      * Creates a new contact group expand job.
61      *
62      * @param group The contact group to expand.
63      * @param parent The parent object.
64      */
65     explicit ContactGroupExpandJob(const KContacts::ContactGroup &group, QObject *parent = nullptr);
66 
67     /**
68      * Creates a new contact group expand job.
69      *
70      * @param name The name of the contact group to expand.
71      * @param parent The parent object.
72      *
73      * @since 4.5
74      */
75     explicit ContactGroupExpandJob(const QString &name, QObject *parent = nullptr);
76 
77     /**
78      * Destroys the contact group expand job.
79      */
80     ~ContactGroupExpandJob() override;
81 
82     /**
83      * Returns the list of contacts.
84      */
85     Q_REQUIRED_RESULT KContacts::Addressee::List contacts() const;
86 
87     /**
88      * Starts the expand job.
89      */
90     void start() override;
91 
92 private:
93     //@cond PRIVATE
94     friend class ContactGroupExpandJobPrivate;
95     std::unique_ptr<ContactGroupExpandJobPrivate> const d;
96 
97     // Already use with QMetaObject::invokeMethod
98     Q_PRIVATE_SLOT(d, void resolveGroup())
99     //@endcond
100 };
101 }
102 
103