libkf5imap-dev 17.12.3-0ubuntu1 / usr / include / KF5 / KIMAP / kimap / fetchjob.h

/*
    Copyright (c) 2009 Kevin Ottens <ervin@kde.org>

    This library is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public License as published by
    the Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This library 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 Library General Public
    License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to the
    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301, USA.
*/

#ifndef KIMAP_FETCHJOB_H
#define KIMAP_FETCHJOB_H

#include "kimap_export.h"

#include "imapset.h"
#include "job.h"

#include <kmime/kmime_content.h>
#include <kmime/kmime_message.h>

namespace KIMAP
{

class Session;
struct Response;
class FetchJobPrivate;

typedef QSharedPointer<KMime::Content> ContentPtr;
typedef QMap<QByteArray, ContentPtr> MessageParts;

typedef QSharedPointer<KMime::Message> MessagePtr;
typedef QList<QByteArray> MessageFlags;

typedef QPair<QByteArray, QVariant> MessageAttribute;

struct Message
{
    qint64 uid;
    qint64 size;
    MessageFlags flags;
    QMap<QByteArray, QVariant> attributes;
    MessageParts parts;
    MessagePtr message;
};


/**
 * Fetch message data from the server
 *
 * All data is returned using the signals, so you need to connect to
 * the relevant signal (or all of them) before starting the job.
 *
 * This job will always use BODY.PEEK rather than BODY to fetch message
 * content, so it will not set the \Seen flag.
 *
 * This job can only be run when the session is in the selected state.
 */
class KIMAP_EXPORT FetchJob : public Job
{
    Q_OBJECT
    Q_DECLARE_PRIVATE(FetchJob)

    friend class SessionPrivate;

public:
    /**
     * Used to indicate what message data should be fetched.
     *
     * This doesn't provide the same fine-grained control over
     * what is fetched that the IMAP FETCH command normally
     * does, but the common cases are catered for.
     */
    class KIMAP_EXPORT FetchScope
    {
    public:
        FetchScope();

        /**
         * Used to indicate what part of the message should be fetched.
         */
        enum Mode {
            /**
             * Fetch RFC-2822 or MIME message headers.
             *
             * To fetch MIME headers for a MIME part, populate the @p parts field.
             *
             * If the RFC-2822 headers are requested (so @p parts is empty), the
             * returned information is:
             * - To, From, Message-id, References In-Reply-To, Subject and Date headers
             * - The message size (in octets)
             * - The internal date of the message
             * - The message flags
             * - The message UID
             */
            Headers,
            /**
             * Fetch the message flags (the UID is also fetched)
             */
            Flags,
            /**
             * Fetch the MIME message body structure (the UID is also fetched)
             */
            Structure,
            /**
             * Fetch the message content (the UID is also fetched)
             *
             * To fetch only certain MIME parts (see Structure), populate the
             * @p parts field.
             */
            Content,
            /**
             * Fetch the complete message.
             */
            Full,
            /**
             * Fetch the message MIME headers and the content of parts specified in the @p parts
             * field.
             *
             * If @p parts is empty, this mode will return the full message, just like
             * FetchScope::Content
             *
             * Use case:
             * -# Start a FetchJob with the FetchScope::Structure mode to retrieve the structure
             *    of the message.
             * -# Parse the structure to identify the parts that are interesting (ie: probably
             *    everything but attachments).
             * -# Start another FetchJob with FetchScope::HeaderAndContent to fetch those parts.
             * -# At the request of the user, you can repeat the step above to fetch the attachments.
             *
             * @since 4.7
             */
            HeaderAndContent,

            /**
             * Fetch message size (in octets), internal date of the message, flags, UID
             * and all RFC822 headers.
             *
             * The @p parts field is ignored when using this scope
             *
             * @since 4.12
             */
            FullHeaders
        };

        /**
         * Specify which message parts to operate on.
         *
         * This refers to multipart-MIME message parts or MIME-IMB encapsulated
         * message parts.
         *
         * Note that this is ignored unless @p mode is Headers or Content.
         *
         * If @p mode is Headers, this sets the parts to get the MIME headers
         * for.  If this list is empty, the headers for the whole message
         * (the RFC-2822 headers) are fetched.
         *
         * If @p mode is Content, this sets the parts to fetch.  Parts are
         * fetched wholesale.  If this list is empty, the whole message body
         * is fetched (all MIME parts together).
         */
        QList<QByteArray> parts;
        /**
         * Specify what message data should be fetched.
         */
        Mode mode;

        /**
         * Specify to fetch only items with mod-sequence higher then @p changedSince.
         *
         * The server must have CONDSTORE capability (RFC4551).
         *
         * Default value is 0 (ignored).
         *
         * @since 4.12
         */
        quint64 changedSince;
    };

    explicit FetchJob(Session *session);
    virtual ~FetchJob();

    /**
     * Set which messages to fetch data for.
     *
     * If sequence numbers are given, isUidBased() should be false.  If UIDs
     * are given, isUidBased() should be true.
     *
     * @param set  the sequence numbers or UIDs of the messages to fetch data for
     */
    void setSequenceSet(const ImapSet &set);
    /**
     * The messages that will be fetched.
     */
    ImapSet sequenceSet() const;

    /**
     * Set how the sequence set should be interpreted.
     *
     * @param uidBased  if @c true the argument to setSequenceSet will be
     *                  interpreted as UIDs, if @c false it will be interpreted
     *                  as sequence numbers
     */
    void setUidBased(bool uidBased);
    /**
     * How to interpret the sequence set.
     *
     * @return  if @c true the result of sequenceSet() should be
     *          interpreted as UIDs, if @c false it should be interpreted
     *          as sequence numbers
     */
    bool isUidBased() const;

    /**
     * Sets what data should be fetched.
     *
     * The default scope is FetchScope::Content (all content parts).
     *
     * @param scope  a FetchScope object describing what data
     *               should be fetched
     */
    void setScope(const FetchScope &scope);
    /**
     * Specifies what data will be fetched.
     */
    FetchScope scope() const;

    // TODO: KF5: Move this to FetchScope
    /**
     * Enables retrieving of Gmail-specific extensions
     *
     * The FETCH response will contain X-GM-MSGID, X-GM-THRID and X-GM-LABELS
     *
     * Do NOT enable this, unless talking to Gmail servers, otherwise the
     * request may fail.
     *
     * @param enabled Whether the Gmail support should be enabled
     * @since 4.14
     */
    void setGmailExtensionsEnabled(bool enabled);

    /**
     * Returns whether Gmail support is enabled
     *
     * @since 4.14
     * @see setGmailExtensionsEnabled()
     */
    bool setGmailExtensionsEnabled() const;

    /**
     * Returns the name of the mailbox the fetch job is executed on.
     *
     * Can only be accessed after the job is actually started, before that
     * returns an empty string.
     *
     * @since 5.6
     */
    QString mailBox() const;

Q_SIGNALS:
    /**
     * Provides header and message results.
     *
     * This signal will be emitted if the requested scope mode
     * was FetchScope::Full, FetchScope::Flags or
     * FetchScope::Headers with no parts specified
     *
     * This signal may be emitted any number of times before
     * the result() signal is emitted.  The result() signal will
     * only be emitted once all results have been reported via
     * one of the signals.
     *
     * Note that, depending on the scope, some of the parameters
     * of this signal may be empty maps.
     *
     * @param mailBox  the name of the mailbox the fetch job was
     *                 executed on
     * @param uids     a map from message sequence numbers to message UIDs;
     *                 this will always be populated
     * @param sizes    a map from message sequence numbers to message sizes
     *                 (sizes are in octets and refer to the transfer encoding of
     *                 the message); populated if the scope is FetchScope::Full or
     *                 FetchScope::Headers
     * @param flags    a map from message sequence numbers to message flags;
     *                 populated if the scope is FetchScope::Flags, FetchScope::Full
     *                 of FetchScope::Headers
     * @param messages a map from message sequence numbers to message contents (including
     *                 headers); populated if the scope is FetchScope::Full,
     *                 FetchScope::Headers or FetchScope::Structure
     *
     * @deprecated Use messagesAvailable() instead.
     */
    KIMAP_DEPRECATED
    void headersReceived(const QString &mailBox,
                         const QMap<qint64, qint64> &uids,
                         const QMap<qint64, qint64> &sizes,
                         const QMap<qint64, KIMAP::MessageFlags> &flags,
                         const QMap<qint64, KIMAP::MessagePtr> &messages);

    /**
     * An overloaded version of headersReceived(), which includes additional attribute
     * specified in the FETCH response, but that don't belong to actual content of the
     * message.
     *
     * @param mailBox  the name of the mailbox the fetch job was
     *                 executed on
     * @param uids     a map from message sequence numbers to message UIDs;
     *                 this will always be populated
     * @param attrs    a map from message sequence numbers to a pair of attribute
     *                 name and value
     * @param sizes    a map from message sequence numbers to message sizes
     *                 (sizes are in octets and refer to the transfer encoding of
     *                 the message); populated if the scope is FetchScope::Full or
     *                 FetchScope::Headers
     * @param flags    a map from message sequence numbers to message flags;
     *                 populated if the scope is FetchScope::Flags, FetchScope::Full
     *                 of FetchScope::Headers
     * @param messages a map from message sequence numbers to message contents (including
     *                 headers); populated if the scope is FetchScope::Full,
     *                 FetchScope::Headers or FetchScope::Structure
     *
     * @overload
     * @since 4.14
     * @deprecated Use messagesAvailable() instead.
     */
    KIMAP_DEPRECATED
    void headersReceived(const QString &mailBox,
                         const QMap<qint64, qint64> &uids,
                         const QMap<qint64, qint64> &sizes,
                         const QMap<qint64, KIMAP::MessageAttribute > &attrs,
                         const QMap<qint64, KIMAP::MessageFlags> &flags,
                         const QMap<qint64, KIMAP::MessagePtr> &messages);

    /**
     * Provides header and message results.
     *
     * This signal will be emitted if the requested scope mode
     * was FetchScope::Content or FetchScope::Headers with no
     * parts specified or FetchScope::Structure.
     *
     * This signal may be emitted any number of times before
     * the result() signal is emitted.  The result() signal will
     * only be emitted once all results have been reported via
     * one of the signals.
     *
     *
     * @param mailBox  the name of the mailbox the fetch job was
     *                 executed on
     * @param uids     a map from message sequence numbers to message UIDs
     * @param messages a map from message sequence numbers to message contents
     *
     * @deprecated Use messagesAvailable() instead.
     */
    KIMAP_DEPRECATED
    void messagesReceived(const QString &mailBox,
                          const QMap<qint64, qint64> &uids,
                          const QMap<qint64, KIMAP::MessagePtr> &messages);

    /**
     * An overloaded version of messagesReceived(), which includes additional attribute
     * specified in the FETCH response, but that don't belong to actual content of the
     * message.
     *
     * @param mailBox  the name of the mailbox the fetch job was
     *                 executed on
     * @param uids     a map from message sequence numbers to message UIDs
     * @param attrs    a map from message sequence numbers to pair of attribute
     *                 name and it's value
     * @param messages a map from message sequence numbers to message contents
     *
     * @overload
     * @since 4.14
     *
     * @deprecated Use messagesAvailable() instead.
     */
    KIMAP_DEPRECATED
    void messagesReceived(const QString &mailBox,
                          const QMap<qint64, qint64> &uids,
                          const QMap<qint64, KIMAP::MessageAttribute > &attrs,
                          const QMap<qint64, KIMAP::MessagePtr> &messages);
    /**
     * Provides header and message results.
     *
     * This signal will be emitted if the requested scope mode
     * was FetchScope::Content or FetchScope::Headers with
     * specified parts.
     *
     * This signal may be emitted any number of times before
     * the result() signal is emitted.  The result() signal will
     * only be emitted once all results have been reported via
     * one of the signals.
     *
     * @param mailBox  the name of the mailbox the fetch job was
     *                 executed on
     * @param uids     a map from message sequence numbers to message UIDs
     * @param parts    a map from message sequence numbers to message part collections
     *
     * @deprecated Use messagesAvailable() instead.
     */
    KIMAP_DEPRECATED
    void partsReceived(const QString &mailBox,
                       const QMap<qint64, qint64> &uids,
                       const QMap<qint64, KIMAP::MessageParts> &parts);

    /**
      * An overloaded version of partsReceived(), which includes additional attribute
      * specified in the FETCH response, but that don't belong to actual content of the
      * message.
      *
      * @param mailBox  the name of the mailbox the fetch job was
      *                 executed on
      * @param uids     a map from message sequence numbers to message UIDs
      * @param attrs    a map from message sequence numbers to pair of attribute
      * @param parts    a map from message sequence numbers to message part collections
      *
      * @overload
      * @since 4.14
      *
      * @deprecated Use messagesAvailable() instead.
      */
    KIMAP_DEPRECATED
    void partsReceived(const QString &mailBox,
                       const QMap<qint64, qint64> &uids,
                       const QMap<qint64, KIMAP::MessageAttribute > &attrs,
                       const QMap<qint64, KIMAP::MessageParts> &parts);

    /**
     * Provides received messages.
     *
     * This signal is emitted when some data are received. The signal can be
     * emitted multiple times as the messages are being received.
     *
     * @param messages A map from message sequence number to message. Not all
     *                 fields may be populated, depending on the fetch scope.
     *
     * @since 5.6
     */
    void messagesAvailable(const QMap<qint64, KIMAP::Message> &messages);

protected:
    void doStart() override;
    void handleResponse(const Response &response) override;

private:
    Q_PRIVATE_SLOT(d_func(), void emitPendings())
};

}

#endif