/*
    This file is part of Akonadi Contact.

    SPDX-FileCopyrightText: 2009 Tobias Koenig <tokoe@kde.org>

    SPDX-License-Identifier: LGPL-2.0-or-later
*/

#pragma once

#include "akonadi-contact-core_export.h"

#include <KContacts/Addressee>
#include <KContacts/ContactGroup>
#include <KJob>

#include <memory>

namespace Akonadi
{
class ContactGroupExpandJobPrivate;

/*!
 * \class Akonadi::ContactGroupExpandJob
 * \brief Job that expands a ContactGroup to a list of contacts.
 * \inmodule AkonadiContactCore
 * \inheaderfile Akonadi/ContactGroupExpandJob
 *
 * This job takes a KContacts::ContactGroup object or a name of a contact group and
 * expands it to a list of KContacts::Addressee objects by creating temporary KContacts::Addressee objects
 * for the KContacts::ContactGroup::Data objects of the group and fetching the
 * complete contacts from the Akonadi storage for the
 * KContacts::ContactGroup::ContactReferences of the group.
 *
 * \code
 *
 * const KContacts::ContactGroup group = ...;
 *
 * Akonadi::ContactGroupExpandJob *job = new Akonadi::ContactGroupExpandJob( group );
 * connect( job, SIGNAL(result(KJob*)), this, SLOT(expandResult(KJob*)) );
 * job->start();
 *
 * ...
 *
 * MyClass::expandResult( KJob *job )
 * {
 *   Akonadi::ContactGroupExpandJob *expandJob = qobject_cast<Akonadi::ContactGroupExpandJob*>( job );
 *   const KContacts::Addressee::List contacts = expandJob->contacts();
 *   // do something with the contacts
 * }
 *
 * \endcode
 *
 * \author Tobias Koenig <tokoe@kde.org>
 * \since 4.4
 */
class AKONADI_CONTACT_CORE_EXPORT ContactGroupExpandJob : public KJob
{
    Q_OBJECT

public:
    /*!
     * Creates a new contact group expand job.
     *
     * \a group The contact group to expand.
     * \a parent The parent object.
     */
    explicit ContactGroupExpandJob(const KContacts::ContactGroup &group, QObject *parent = nullptr);

    /*!
     * Creates a new contact group expand job.
     *
     * \a name The name of the contact group to expand.
     * \a parent The parent object.
     *
     * \since 4.5
     */
    explicit ContactGroupExpandJob(const QString &name, QObject *parent = nullptr);

    /*!
     * Destroys the contact group expand job.
     */
    ~ContactGroupExpandJob() override;

    /*!
     * Returns the list of contacts.
     */
    [[nodiscard]] KContacts::Addressee::List contacts() const;

    /*!
     * Starts the expand job.
     */
    void start() override;

private:
    friend class ContactGroupExpandJobPrivate;
    std::unique_ptr<ContactGroupExpandJobPrivate> const d;

    // Already use with QMetaObject::invokeMethod
    Q_PRIVATE_SLOT(d, void resolveGroup())
};
}
