summaryrefslogtreecommitdiff
path: root/kimap/getmetadatajob.h
diff options
context:
space:
mode:
authorChristian Mollekopf <chrigi_1@fastmail.fm>2012-06-25 23:43:13 (GMT)
committerChristian Mollekopf <chrigi_1@fastmail.fm>2012-06-25 23:43:13 (GMT)
commite21e62c14f5aae99d46643065fcb86e2e3abe230 (patch)
tree71d79d2de0b0f82f8b0a6ca3b8b09308d198ed33 /kimap/getmetadatajob.h
parent172803b38237e38a494aca62fffda918e5799d20 (diff)
downloadlibcalendaring-e21e62c14f5aae99d46643065fcb86e2e3abe230.tar.gz
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.
Diffstat (limited to 'kimap/getmetadatajob.h')
-rw-r--r--kimap/getmetadatajob.h196
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