initial import of kimap from

commit b54a325116b194da090f900c9a538710759eb303
Author: Stephen Kelly <steveire@gmail.com>
Date:   Sun May 6 20:44:53 2012 +0200

    Revert "Port to const QRegExp API."

    This reverts commit 0ca0dfc7e0ca8095efd0b060d1d5e26ac9ceb379.

    The qtbase commit requiring this was reverted.

1 files changed, 196 insertions, 0 deletions

diff --git a/kimap/getmetadatajob.h b/kimap/getmetadatajob.h
new file mode 100644
index 0000000..0ba43eb
--- /dev/null
+++ b/kimap/getmetadatajob.h
@@ -0,0 +1,196 @@
+/*
+    Copyright (c) 2009 Andras Mantia <amantia@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_GETMETADATAJOB_H
+#define KIMAP_GETMETADATAJOB_H
+
+#include "kimap_export.h"
+
+#include "metadatajobbase.h"
+
+namespace KIMAP {
+
+class Session;
+struct Message;
+class GetMetaDataJobPrivate;
+
+/**
+ * Fetches mailbox metadata.
+ *
+ * Provides support for the IMAP METADATA extension; both the
+ * final RFC version
+ * (<a href="http://tools.ietf.org/html/rfc5464">RFC 5464</a>)
+ * and the older, incompatible draft version (known as ANNOTATEMORE)
+ * (<a
+ * href="http://tools.ietf.org/html/draft-daboo-imap-annotatemore-07"
+ * >draft-daboo-imap-annotatemore-07</a>).  See setServerCompatibility().
+ *
+ * This job can only be run when the session is in the
+ * authenticated (or selected) state.
+ *
+ * If the server supports ACLs, the user will need the
+ * Acl::Lookup right on the mailbox, as well as one of
+ * - Acl::Read
+ * - Acl::KeepSeen
+ * - Acl::Write
+ * - Acl::Insert
+ * - Acl::Post
+ * Otherwise, the user must be able to list the mailbox
+ * and either read or write the message content.
+ *
+ * Note also that on servers that implement the Annotatemore
+ * version of the extension, only Acl::Lookup rights are
+ * required (ie: the user must be able to list the mailbox).
+ */
+class KIMAP_EXPORT GetMetaDataJob : public MetaDataJobBase
+{
+  Q_OBJECT
+  Q_DECLARE_PRIVATE( GetMetaDataJob )
+
+  friend class SessionPrivate;
+
+  public:
+    explicit GetMetaDataJob( Session *session );
+    virtual ~GetMetaDataJob();
+
+    /**
+     * Used to specify the depth of the metadata heirachy to walk.
+     */
+    enum Depth {
+      NoDepth = 0, /**< Only the requested entries */
+      OneLevel,    /**< The requested entries and all their direct children */
+      AllLevels    /**< The requested entries and all their descendants */
+    };
+
+    Q_DECLARE_FLAGS( Depths, Depth )
+
+    /**
+     * Add an entry to the query list.
+     *
+     * See SetMetaDataJob for a description of metadata entry names.
+     *
+     * When operating in Annotatemore mode, you should provide an attribute
+     * name.  Typically this will be "value", "value.priv" or "value.shared",
+     * although you might want to fetch the "content-type" or
+     * "content-language" attributes as well.
+     *
+     * @param entry      the metadata entry name
+     * @param attribute  the attribute name, in Annotatemore mode
+     */
+     void addEntry( const QByteArray &entry, const QByteArray &attribute = QByteArray() );
+
+    /**
+     * Limits the size of returned metadata entries.
+     *
+     * In order to save time or bandwidth, it is possible to prevent the
+     * server from returning metadata entries that are larger than a
+     * certain size.  These entries will simply not appear in the
+     * list returned by allMetaData(), and will not be accessible using
+     * metaData().
+     *
+     * Note that this is only used when the server capability mode is
+     * Metadata.
+     *
+     * The default is no limit (-1).  A value of less than -1 will cause
+     * the job to fail.
+     *
+     * @param size  the entry size limit, in octets, or -1 for no limit
+     */
+    void setMaximumSize( qint64 size );
+
+    /**
+     * Sets whether to retrieve children or descendants of the requested entries.
+     *
+     * Metadata entry names are heirachical, much like UNIX path names.
+     * It therefore makes sense to ask for an entry and all its children
+     * (OneLevel) or an entry and all its descendants (AllLevels).
+     *
+     * For example, /shared/foo/bar/baz is a child of /shared/foo/bar and a
+     * descendent of /shared/foo.  So if you request the entry "/shared/foo"
+     * with depth NoDepth, you will only get the "/shared/foo" entry.  If
+     * you set the depth to OneLevel, you will also get "/shared/foo/bar".
+     * If you set the depth to AllLevels, you will also get
+     * "/shared/foo/bar/baz", and every other metadata entry that starts
+     * with "/shared/foo/".
+     *
+     * Note that this is only used when the server capability mode is
+     * Metadata.
+     *
+     * @param depth  the depth of the metadata tree to return
+     */
+    void setDepth( Depth depth );
+
+    /**
+     * Get a single metadata entry.
+     *
+     * The metadata must have been requested using addEntry(), and
+     * the job must have completed successfully, or this method
+     * will not return anything.
+     *
+     * Note that if setMaximumSize() was used to limit the size of
+     * returned metadata, this method may return an empty QByteArray
+     * even if the metadata entry was requested and exists on the
+     * server.  This will happen when the metadata entry is larger
+     * than the size limit given to setMaximumSize().
+     *
+     * @param mailBox    the mailbox the metadata is attached to, or
+     *                   an empty string for server metadata
+     * @param entry      the entry to get
+     * @param attribute  (only in Annotatemore mode) the attribute to get
+     * @return  the metadata entry value
+     */
+    // XXX: what's with the mailBox argument in a class that has setMailBox()?
+    //      KJobs are not intended to be run more than once
+    QByteArray metaData( const QString &mailBox, const QByteArray &entry,
+                         const QByteArray &attribute = QByteArray() ) const;
+
+    /**
+     * Get all the metadata for a given mailbox.
+     *
+     * The returned map is from metadata entry names to attributes or values.
+     *
+     * If operating in Metadata mode, the metadata value is stored against the
+     * empty QByteArray:
+     * @code
+     * map = job.allMetaData( "INBOX" );
+     * QByteArray value = map[ "/shared/comment" ].value( QByteArray() );
+     * @endcode
+     *
+     * The equivalent in Annotatemore mode would be:
+     * @code
+     * map = job.allMetaData( "INBOX" );
+     * QByteArray value = map[ "/comment" ].value( "value.shared" );
+     * @endcode
+     *
+     * @param mailBox  a mailbox name or an empty string for server metadata
+     * @return  a map from metadata entry names to attributes or values
+     */
+    // XXX: what's with the mailBox argument in a class that has setMailBox()?
+    //      KJobs are not intended to be run more than once
+    QMap<QByteArray, QMap<QByteArray, QByteArray> > allMetaData( const QString &mailBox ) const;
+
+  protected:
+    virtual void doStart();
+    virtual void handleResponse( const Message &response );
+
+};
+
+}
+
+#endif