File indexing completed on 2024-06-23 05:06:47

 /*
     SPDX-FileCopyrightText: 2008 Kevin Krammer <kevin.krammer@gmx.at>
     SPDX-FileCopyrightText: 2009 Volker Krause <vkrause@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #pragma once
 
 #include "akonadicore_export.h"
 
 #include <QSet>
 #include <QSharedDataPointer>
 
 #include <QStringList>
 
 namespace Akonadi
 {
 class CollectionFetchScopePrivate;
 
 /**
  * @short Specifies which parts of a collection should be fetched from the Akonadi storage.
  *
  * When collections are fetched from the server either by using CollectionFetchJob
  * explicitly or when it is being used internally by other classes, e.g. Akonadi::Monitor,
  * the scope of the fetch operation can be tailored to the application's current needs.
  *
  * Note that CollectionFetchScope always includes fetching collection attributes.
  *
  * There are two supported ways of changing the currently active CollectionFetchScope
  * of classes:
  * - in-place: modify the CollectionFetchScope object the other class holds as a member
  * - replace: replace the other class' member with a new scope object
  *
  * Example: modifying a CollectionFetchJob's scope @c in-place
  * @code
  * Akonadi::CollectionFetchJob *job = new Akonadi::CollectionFetchJob( collection );
  * job->fetchScope().setIncludeUnsubscribed( true );
  * @endcode
  *
  * Example: @c replacing a CollectionFetchJob's scope
  * @code
  * Akonadi::CollectionFetchScope scope;
  * scope.setIncludeUnsubscribed( true );
  *
  * Akonadi::CollectionFetchJob *job = new Akonadi::CollectionFetchJob( collection );
  * job->setFetchScope( scope );
  * @endcode
  *
  * This class is implicitly shared.
  *
  * @author Volker Krause <vkrause@kde.org>
  * @since 4.4
  */
 class AKONADICORE_EXPORT CollectionFetchScope
 {
 public:
     /**
      * Describes the ancestor retrieval depth.
      */
     enum AncestorRetrieval {
         None, ///< No ancestor retrieval at all (the default)
         Parent, ///< Only retrieve the immediate parent collection
         All ///< Retrieve all ancestors, up to Collection::root()
     };
 
     /**
      * Creates an empty collection fetch scope.
      *
      * Using an empty scope will only fetch the very basic meta data of collections,
      * e.g. local id, remote id and content mimetypes.
      */
     CollectionFetchScope();
 
     /**
      * Creates a new collection fetch scope from an @p other.
      */
     CollectionFetchScope(const CollectionFetchScope &other);
 
     /**
      * Destroys the collection fetch scope.
      */
     ~CollectionFetchScope();
 
     /**
      * Assigns the @p other to this scope and returns a reference to this scope.
      */
     CollectionFetchScope &operator=(const CollectionFetchScope &other);
 
     /**
      * Describes the list filter
      *
      * @since 4.14
      */
     enum ListFilter {
         NoFilter, ///< No filtering, retrieve all collections
         Display, ///< Only retrieve collections for display, taking the local preference and enabled into account.
         Sync, ///< Only retrieve collections for synchronization, taking the local preference and enabled into account.
         Index, ///< Only retrieve collections for indexing, taking the local preference and enabled into account.
         Enabled ///< Only retrieve enabled collections, ignoring the local preference.
     };
 
     /**
      * Sets a filter for the collections to be listed.
      *
      * Note that collections that do not match the filter are included if required to complete the tree.
      *
      * @since 4.14
      */
     void setListFilter(ListFilter);
 
     /**
      * Returns the list filter.
      *
      * @see setListFilter()
      * @since 4.14
      */
     [[nodiscard]] ListFilter listFilter() const;
 
     /**
      * Returns whether collection statistics should be included in the retrieved results.
      *
      * @see setIncludeStatistics()
      */
     [[nodiscard]] bool includeStatistics() const;
 
     /**
      * Sets whether collection statistics should be included in the retrieved results.
      *
      * @param include @c true to include collection statistics, @c false otherwise (the default).
      */
     void setIncludeStatistics(bool include);
 
     /**
      * Returns the resource identifier that is used as filter.
      *
      * @see setResource()
      */
     [[nodiscard]] QString resource() const;
 
     /**
      * Sets a resource filter, that is only collections owned by the specified resource are
      * retrieved.
      *
      * @param resource The resource identifier.
      */
     void setResource(const QString &resource);
 
     /**
      * Sets a content mimetypes filter, that is only collections that contain at least one of the
      * given mimetypes (or their parents) are retrieved.
      *
      * @param mimeTypes A list of mime types
      */
     void setContentMimeTypes(const QStringList &mimeTypes);
 
     /**
      * Returns the content mimetypes filter.
      *
      * @see setContentMimeTypes()
      */
     [[nodiscard]] QStringList contentMimeTypes() const;
 
     /**
      * Sets how many levels of ancestor collections should be included in the retrieval.
      *
      * Only the ID and the remote ID of the ancestor collections are fetched. If
      * you want more information about the ancestor collections, like their name,
      * you will need to do an additional CollectionFetchJob for them.
      *
      * @param ancestorDepth The desired ancestor retrieval depth.
      */
     void setAncestorRetrieval(AncestorRetrieval ancestorDepth);
 
     /**
      * Returns the ancestor retrieval depth.
      *
      * @see setAncestorRetrieval()
      */
     [[nodiscard]] AncestorRetrieval ancestorRetrieval() const;
 
     /**
      * Sets the fetch scope for ancestor retrieval.
      *
      * @see setAncestorRetrieval()
      */
     void setAncestorFetchScope(const CollectionFetchScope &scope);
 
     /**
      * Returns the fetch scope for ancestor retrieval.
      */
     [[nodiscard]] CollectionFetchScope ancestorFetchScope() const;
 
     /**
      * Returns the fetch scope for ancestor retrieval.
      */
     CollectionFetchScope &ancestorFetchScope();
 
     /**
      * Returns all explicitly fetched attributes.
      *
      * @see fetchAttribute()
      */
     [[nodiscard]] QSet<QByteArray> attributes() const;
 
     /**
      * Sets whether the attribute of the given @p type should be fetched.
      *
      * @param type The attribute type to fetch.
      * @param fetch @c true if the attribute should be fetched, @c false otherwise.
      */
     void fetchAttribute(const QByteArray &type, bool fetch = true);
 
     /**
      * Sets whether the attribute of the requested type should be fetched.
      *
      * @param fetch @c true if the attribute should be fetched, @c false otherwise.
      */
     template<typename T>
     inline void fetchAttribute(bool fetch = true)
     {
         T dummy;
         fetchAttribute(dummy.type(), fetch);
     }
 
     /**
      * Sets whether only the id or the complete tag should be fetched.
      *
      * The default is @c false.
      *
      * @since 4.15
      */
     void setFetchIdOnly(bool fetchIdOnly);
 
     /**
      * Sets whether only the id of the tags should be retrieved or the complete tag.
      *
      * @see tagFetchScope()
      * @since 4.15
      */
     [[nodiscard]] bool fetchIdOnly() const;
 
     /**
      * Ignore retrieval errors while fetching collections, and always deliver what is available.
      *
      * This flag is useful to fetch a list of collections, where some might no longer be available.
      *
      * @since KF6
      */
     void setIgnoreRetrievalErrors(bool enabled);
 
     /**
      * Returns whether retrieval errors should be ignored.
      *
      * @see setIgnoreRetrievalErrors()
      * @since KF6
      */
     [[nodiscard]] bool ignoreRetrievalErrors() const;
 
     /**
      * Returns @c true if there is nothing to fetch.
      */
     [[nodiscard]] bool isEmpty() const;
 
 private:
     /// @cond PRIVATE
     QSharedDataPointer<CollectionFetchScopePrivate> d;
     /// @endcond
 };
 
 }