danbooru-client/src/libdanbooru/servicebase.h

/*
 * Copyright 2015 Luca Beltrame <lbeltrame@kde.org>
 *
 * This file is part of Danbooru Client.
 *
 * Danbooru Client is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Danbooru Client is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Danbooru Client. If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef DANBOORU_SERVICEBASE_H
#define DANBOORU_SERVICEBASE_H

// Own

#include "danbooru.h"
#include "danboorupost.h"
#include "danboorutag.h"
#include "danboorupool.h"

// Qt

#include <QObject>
#include <QString>
#include <QStringList>
#include <QSet>

// KF5

#include <KImageCache>


namespace Danbooru
{

enum ApiType {
    OriginalDanbooru = 7000,
    KonachanDanbooru = 7001,
    Gelbooru = 7002,
    Unknown = 7003
};

enum SupportedOperation {
        PostDownload = 6000,
        TagDownload = 6001,
        TagSearch = 6002,
        PoolDownload = 6003,
        RelatedTagSearch = 6004
};

Q_DECLARE_FLAGS(SupportedOperations, SupportedOperation)

class DanbooruServiceBase: public QObject
{

Q_OBJECT

private:

    // URI functions

    virtual const QLatin1String postUri() = 0;
    virtual const QLatin1String poolUri() = 0;
    virtual const QLatin1String artistUri() = 0;
    virtual const QLatin1String poolDataUri() = 0;
    virtual const QLatin1String relatedTagUri() = 0;

    // member variables

    QUrl m_url;
    QString m_username;
    QString m_password;
    QSet<QString> m_blacklist;
    DanbooruPost::Ratings m_maxRating;
    int m_maxPosts;
    int m_currentPage;
    QStringList m_tags;

    unsigned int m_postsToFetch; // To tell when to quit

    KImageCache *m_cache; // Pixmap cache

public:

    explicit DanbooruServiceBase();
    virtual ~DanbooruServiceBase();

    /////////////////////////////////////////////
    // Functions shared with all implementations
    /////////////////////////////////////////////

    /**
     * @brief Return the post ratings required for download.
     *
     * If a post does not meet the allowed rating, it is not downloaded (e.g., an Explicit post with
     * only Safe and Questionable ratings).
     *
     * @return a QStringList with the allowed ratings.
     */
    const QStringList allowedRatings() const;

    /**
     * @brief Return the api type of the searvice.
     **/
    int apiType() const;

    /**
     * @brief Return the blacklisted tags for the service
     *
     * If a tag is in the blacklist, posts containing it will not be downloaded.
     *
     * @return a QSet containing the blacklisted tags,
     **/
    const QSet<QString> blacklist() const;

    /**
     * @brief Return the current page.
     *
     * Danbooru APIs are heavily page-based due to their request limits (usually 100 posts per request).
     * Therefore, to move to the next batch of posts, one needs to specify a "page" number. Service
     * implementations need this to determine which set of posts to download.
     *
     * @return The current page number.
     *
     **/
    int currentPage() const;

    /**
     * @return The maximum allowed rating for a post.
     **/
    const DanbooruPost::Ratings maximumAllowedRating() const;

    /**
     * @return The number of posts downloaded for each page (max 100)
     **/
    int maxPosts() const;

    /**
     * @brief Move to the next post page and retrieve new posts.
     *
     **/
    Q_INVOKABLE void nextPostPage();

    /**
     * @brief Move to the next pool page and retrieve new posts associated to the pool.
     * The default implementation does nothing.
     *
     **/
    Q_INVOKABLE virtual void nextPoolPage();

    /**
     * @return A QStringList containing the currently-selected tags
     **/
    QStringList postTags();

    /**
     * @brief Resets the service to the default state, clearing the page counters.
     **/
    void reset();

    /**
     * @return The operations supported by the API.
     **/
    virtual SupportedOperations supportedOperations() const = 0;

    ///////////////////////////////
    // Common setters (non-virtual)
    ///////////////////////////////

    /**
     * @brief Set blacklisted tags.
     *
     * Posts with blacklisted tags are not downloaded.
     *
     * @param blacklist A QSet<QString> including unwanted tags.
     *
     **/
    void setBlacklist(const QStringList &blacklist);

    /**
    * @brief Set the tag blacklist.
    *
    * If a tag is in the blacklist, posts tagged with it will not be downloaded.
    *
    **/
    void setBlacklist(const QSet<QString> &blacklist);

    /**
     * @brief Set the board URL to connect to.
     *
     * @param url The URL to connect to.
     */
    void setBoardUrl(const QUrl &url);

    /**
     * @brief Set the current page.
     **/
    void setCurrentPage(int page);


    /**
     * @brief Set an image cache to use.
     *
     * @param cache A pointer to an instance of KImageCache.
     */
    void setImageCache(KImageCache *cache);

    /**
     * @brief Set the maximum allowed rating for the board.
     *
     * Posts whose rating is higher than the maximuk allowed will not be
     * downloaded.
     *
     **/
    void setMaximumAllowedRating(DanbooruPost::Rating rating);

    /**
     * @brief Set the maximum number of posts to download for each page.
     **/
    void setMaxPosts(int number);

    /**
     * @brief Set the password used for login.
     *
     * @warning It should not be the password itself, but a SHA1 hash
     *  with a specific salt (which is board-dependent; check their
     *  API access rules).
     *
     * @param password The salted password to use.
     *
     **/
    void setPassword(const QString &password);

    /**
     * @brief Set the tags needed to fetch posts
     *
     * This basically sets the tags to "search" for: the way they are used
     * is API-dependent.
     *
     * **/
    void setPostTags(const QStringList &tags);

    /**
     * @brief Set username for login.
     *
     * @param username The username to use.
     *
     **/
    void setUserName(const QString &username);

    ////////////////////////////////////
    // API specific operations (virtual)
    ////////////////////////////////////

    /**
     * @brief Get posts from a Danbooru board.
     *
     * The default implementation does nothing.
     *
     **/
    virtual void getPostList() = 0;

    /**
     * @brief Get a list of pools from a Danbooru board.
     *
     * The default implementation does nothing.
     *
     * @remarks
     *      This does not actually retrieve pool contents, only their definitions.
     *
     **/
    virtual void getPoolList() = 0;

    /**
     * @brief retrieve posts associated to a specific pool from a Danbooru board.
     *
     * Use this function when you want to actually retrieve posts associated to pools obtained through getPoolList.
     *
     * @param poolId the ID associated to the pool
     * @param page the page containing posts (for pools with more than 100 posts).
     *
     * @remarks
     *  This operation may not present in all Danbooru implementations.
     */
    virtual void getPool(int poolId, int page = 1) = 0;

    /**
     * @brief Get a list of tags from the board
     *
     * If name is supplied, a list of tags including the exact name of the
     * tag is fetched from Danbooru, otherwise the most recent tags are
     * retrieved.
     *
     * The tagDownloaded signal is emitted every time a tag has been
     * retrieved.
     *
     * @param limit The number of tags to get.
     * @param name The name of the tag to retrieve, or an empty string
     *
     * @remarks
     *      May not be supported by all APIs.
     *
     **/
    virtual void getTagList(int limit = 10, QString name = "") = 0;

    /**
     * @brief Get tags related to a specific, user supplied list.
     *
     * @param tags The tags to query for related terms
     * @param tagType The type of tag to query for
     *
     * @remarks
     *      May not be supported by all APIs.
     *
     **/
    virtual void getRelatedTags(const QStringList &tags,
                                DanbooruTag::TagType tagType = DanbooruTag::General) = 0;

Q_SIGNALS:

    /**
     * Emitted when there are no more posts to download.
     *
     * Connect to this signal to know when downloading is complete.
     *
     **/
    void postDownloadFinished();

    /**
     * Emitted when there are no more pools to download.
     **/
    void poolDownloadFinished();

    /**
     * Emitted when a download error occurred.
     *
     * The parameter contains the error string.
     *
     **/
    void downloadError(QString error);

    /**
     * Emitted when a post has been downloaded.
     *
     * The parameter contains a pointer to the post that has been
     * downloaded.
     **/
    void postDownloaded(Danbooru::DanbooruPost *post);

    /**
     * Emitted when a pool has been downloaded.
     *
     * The parameter contains a pointer to the pool that has been
     * downloaded.
     **/
    void poolDownloaded(Danbooru::DanbooruPool *pool);

    /**
     * Emitted when a tag has been downloaded.
     *
     * The parameter contains a pointer to the tag that has been
     * downloaded.
     **/
    void tagDownloaded(Danbooru::DanbooruTag *tag);

};

Q_DECLARE_OPERATORS_FOR_FLAGS(Danbooru::SupportedOperations)


}

#endif