diff --git a/kimap/Mainpage.dox b/kimap/Mainpage.dox
index 117e69c29..71fb5b569 100644
--- a/kimap/Mainpage.dox
+++ b/kimap/Mainpage.dox
@@ -1,25 +1,35 @@
/*!
- * @mainpage KIMAP - an API for handling IMAP data.
+ * @mainpage KIMAP - a job-based API for interacting with IMAP servers
*
* @section purpose Purpose
*
- * The kimap library contains an API for the handling of IMAP data.
+ * This library provides a job-based API for interacting with an IMAP4rev1 server.
+ * It manages connections, encryption and parameter quoting and encoding, but
+ * otherwise provides quite a low-level interface to the protocol. This library
+ * does not implement an IMAP client; it merely makes it easier to do so.
*
- * @section desc Description
+ * Users should be familiar with
+ * RFC 3501,
+ * as well as other related RFCs such as
+ * RFC 4315
+ * and
+ * RFC 2822,
+ * although the library hides some of the nastier details like the encoding and quoting of
+ * strings.
*
- * Insert a nice description here.
+ * @section desc Description
*
* @authors
* The major authors of this library are:\n
* Sven Carstens \
*
* @maintainers
* Tom Albers \,
* Volker Krause \,
* Allen Winter \
*
* @licenses
* @lgpl
*/
// DOXYGEN_PROJECTNAME=KIMAP Library
diff --git a/kimap/acl.h b/kimap/acl.h
index 954017618..a4ae47bcb 100644
--- a/kimap/acl.h
+++ b/kimap/acl.h
@@ -1,67 +1,85 @@
/*
Copyright (c) 2009 Andras Mantia
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_ACL_H
#define KIMAP_ACL_H
#include "kimap_export.h"
namespace KIMAP {
+/**
+ * Operations for dealing with mailbox permissions.
+ */
namespace Acl {
+/**
+ * Possible rights that can be held for a mailbox
+ */
enum Right {
None = 0x000000,
Lookup = 0x000001,
Read = 0x000002,
KeepSeen = 0x000004,
Write = 0x000008,
Insert = 0x000010,
Post = 0x000020,
Create = 0x000040,
CreateMailbox = 0x000080,
DeleteMailbox = 0x000100,
DeleteMessage = 0x000200,
Delete = 0x000400,
Admin = 0x000800,
Expunge = 0x001000,
WriteShared = 0x002000,
Custom0 = 0x004000,
Custom1 = 0x008000,
Custom2 = 0x010000,
Custom3 = 0x020000,
Custom4 = 0x040000,
Custom5 = 0x080000,
Custom6 = 0x100000,
Custom7 = 0x200000,
Custom8 = 0x400000,
Custom9 = 0x800000
};
Q_DECLARE_FLAGS(Rights, Right)
+/**
+ * Convert a set of rights into text format
+ *
+ * No modifier flag ('+' or '-') will be included.
+ */
KIMAP_EXPORT QByteArray rightsToString( Rights rights );
+/**
+ * Convert the text form of a set of rights into a Rights bitflag
+ *
+ * Modifier flags ('+' and '-') are ignored, as are any unknown
+ * characters. This method will not complain if you give it
+ * something that is not a list of rights.
+ */
KIMAP_EXPORT Rights rightsFromString( const QByteArray &string );
}
}
Q_DECLARE_OPERATORS_FOR_FLAGS( KIMAP::Acl::Rights )
#endif
diff --git a/kimap/acljobbase.h b/kimap/acljobbase.h
index 3bc1e1ac7..d074cb10d 100644
--- a/kimap/acljobbase.h
+++ b/kimap/acljobbase.h
@@ -1,64 +1,67 @@
/*
Copyright (c) 2009 Andras Mantia
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_ACLJOBBASE_H
#define KIMAP_ACLJOBBASE_H
#include "kimap_export.h"
#include "acl.h"
#include "job.h"
namespace KIMAP {
class Session;
struct Message;
class AclJobBasePrivate;
-/** @short Base class of Acl related jobs. It cannot be used directly, you must subclass it and reimplement at least the
-doStart() method.
+/**
+ * Base class of Acl related jobs.
+ *
+ * This class cannot be used directly, you must subclass it and reimplement
+ * at least the doStart() method.
*/
class KIMAP_EXPORT AclJobBase : public Job
{
Q_OBJECT
Q_DECLARE_PRIVATE(AclJobBase)
friend class SessionPrivate;
public:
AclJobBase( Session *session );
virtual ~AclJobBase();
enum AclModifier {
Add = 0,
Remove,
Change
};
void setMailBox( const QString &mailBox );
QString mailBox() const;
protected:
explicit AclJobBase( JobPrivate &dd );
};
}
#endif
diff --git a/kimap/appendjob.h b/kimap/appendjob.h
index d1919bb2e..e8e33e122 100644
--- a/kimap/appendjob.h
+++ b/kimap/appendjob.h
@@ -1,62 +1,108 @@
/*
Copyright (c) 2009 Kevin Ottens
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_APPENDJOB_H
#define KIMAP_APPENDJOB_H
#include "kimap_export.h"
#include "job.h"
namespace KIMAP {
class Session;
struct Message;
class AppendJobPrivate;
+/**
+ * Appends a message to a mailbox.
+ *
+ * This job can only be run when the session is in the
+ * authenticated (or selected) state.
+ */
class KIMAP_EXPORT AppendJob : public Job
{
Q_OBJECT
Q_DECLARE_PRIVATE(AppendJob)
friend class SessionPrivate;
public:
AppendJob( Session *session );
virtual ~AppendJob();
+ /**
+ * Set the mailbox to append the message to.
+ *
+ * If the mailbox does not exist, it will not automatically
+ * be created and the command will fail.
+ *
+ * @param mailBox the (unquoted) name of the mailbox
+ */
void setMailBox( const QString &mailBox );
+ /**
+ * The mailbox that the message will be appended to.
+ */
QString mailBox() const;
+ /**
+ * Set the flags that should be applied to the appended message.
+ *
+ * @param flags a list of flags
+ */
void setFlags( const QList &flags);
+ /**
+ * The flags that will be set on the appended message.
+ */
QList flags() const;
+ /**
+ * The content of the message.
+ *
+ * This should be in RFC-2822 format, although some required header
+ * lines may be omitted in certain cases, for example when appending
+ * to a Drafts folder.
+ *
+ * @param content usually an RFC-2822 message
+ */
void setContent( const QByteArray &content );
+ /**
+ * The content that the message will have.
+ */
QByteArray content() const;
+ /**
+ * The UID of the new message.
+ *
+ * This will be zero if it is unknown.
+ *
+ * The UID will not be known until the job has been successfully
+ * executed, and it will only be known at all if the server
+ * supports the UIDPLUS extension (RFC 4315).
+ */
qint64 uid() const;
protected:
virtual void doStart();
virtual void handleResponse(const Message &response);
};
}
#endif
diff --git a/kimap/capabilitiesjob.h b/kimap/capabilitiesjob.h
index 8262f2f12..0306f26e8 100644
--- a/kimap/capabilitiesjob.h
+++ b/kimap/capabilitiesjob.h
@@ -1,56 +1,78 @@
/*
Copyright (c) 2009 Kevin Ottens
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_CAPABILITIESJOB_H
#define KIMAP_CAPABILITIESJOB_H
#include "kimap_export.h"
#include "job.h"
namespace KIMAP {
class Session;
struct Message;
class CapabilitiesJobPrivate;
+/**
+ * Checks server capabilities.
+ *
+ * This job can be run in any open session.
+ *
+ * This simply asks the server what capabilities it supports
+ * (using the CAPABILITY command) and returns the list
+ * provided by the server. The list may, therefore, be
+ * inaccurate: the server may claim to support something
+ * it does not implement properly, or it may omit a feature
+ * that it does, in reality, support.
+ */
class KIMAP_EXPORT CapabilitiesJob : public Job
{
Q_OBJECT
Q_DECLARE_PRIVATE(CapabilitiesJob)
friend class SessionPrivate;
public:
CapabilitiesJob( Session *session );
virtual ~CapabilitiesJob();
+ /**
+ * The capabilities the server claims to support.
+ *
+ * This will return an empty list until the job has completed.
+ */
QStringList capabilities() const;
Q_SIGNALS:
+ /**
+ * Notifies listeners that the capabilities have been fetched.
+ *
+ * @param capabilities The capabilities the server claims to support.
+ */
void capabilitiesReceived( const QStringList &capabilities );
protected:
virtual void doStart();
virtual void handleResponse( const Message &response );
};
}
#endif
diff --git a/kimap/closejob.h b/kimap/closejob.h
index 6affb2bf8..a2347f00c 100644
--- a/kimap/closejob.h
+++ b/kimap/closejob.h
@@ -1,50 +1,68 @@
/*
Copyright (c) 2009 Andras Mantia
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_CLOSEJOB_H
#define KIMAP_CLOSEJOB_H
#include "kimap_export.h"
#include "job.h"
namespace KIMAP {
class Session;
struct Message;
class CloseJobPrivate;
+/**
+ * Closes the current mailbox.
+ *
+ * This job can only be run when the session is in the selected state.
+ *
+ * Permanently removes all messages that have the \\Deleted
+ * flag set from the currently selected mailbox, and returns
+ * to the authenticated state from the selected state.
+ *
+ * The server will not provide any notifications of which
+ * messages were expunged, so this is quicker than doing
+ * an expunge and then implicitly closing the mailbox
+ * (by selecting or examining another mailbox or logging
+ * out).
+ *
+ * No messages are removed if the mailbox is open in a read-only
+ * state.
+ */
class KIMAP_EXPORT CloseJob : public Job
{
Q_OBJECT
Q_DECLARE_PRIVATE(CloseJob)
friend class SessionPrivate;
public:
explicit CloseJob( Session *session );
virtual ~CloseJob();
protected:
virtual void doStart();
};
}
#endif
diff --git a/kimap/copyjob.h b/kimap/copyjob.h
index 5b43b2590..a80076aaa 100644
--- a/kimap/copyjob.h
+++ b/kimap/copyjob.h
@@ -1,63 +1,120 @@
/*
Copyright (c) 2009 Andras Mantia
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_COPYJOB_H
#define KIMAP_COPYJOB_H
#include "kimap_export.h"
#include "job.h"
#include "imapset.h"
namespace KIMAP {
class Session;
struct Message;
class CopyJobPrivate;
+/**
+ * Copies one or more messages to another mailbox.
+ *
+ * This job can only be run when the session is in the selected state.
+ */
class KIMAP_EXPORT CopyJob : public Job
{
Q_OBJECT
Q_DECLARE_PRIVATE(CopyJob)
friend class SessionPrivate;
public:
explicit CopyJob( Session *session );
virtual ~CopyJob();
+ /**
+ * Sets the destination mailbox.
+ *
+ * If the mailbox does not exist, the server should not create
+ * it automatically and the job should fail. Note, however,
+ * that a conforming server may create the mailbox automatically.
+ *
+ * @param mailBox the (unquoted) name of the mailbox where the
+ * messages should be copied to
+ */
void setMailBox( const QString &mailBox );
+ /**
+ * The destination mailbox
+ */
QString mailBox() const;
+ /**
+ * Sets the messages to be copied
+ *
+ * If sequence numbers are given, isUidBased() should be false. If UIDs
+ * are given, isUidBased() should be true.
+ *
+ * RFC 3501 is unclear as to what should happen if invalid sequence numbers
+ * are passed. If non-existent UIDs are passed, they will be ignored.
+ *
+ * @param set the sequence numbers or UIDs of the messages to be copied
+ */
void setSequenceSet( const ImapSet &set );
+ /**
+ * The messages that will be copied.
+ *
+ * isUidBased() can be used to check whether the ImapSet contains
+ * sequence numbers or UIDs.
+ *
+ * @return the sequence numbers or UIDs of the messages to be copied
+ */
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;
+ /**
+ * The UIDs of the new copies of the messages
+ *
+ * This will be an empty set if no messages have been copied yet
+ * or if the server does not support the UIDPLUS extension.
+ */
ImapSet resultingUids() const;
protected:
virtual void doStart();
virtual void handleResponse(const Message &response);
};
}
#endif
diff --git a/kimap/createjob.h b/kimap/createjob.h
index d55d5888f..a494480db 100644
--- a/kimap/createjob.h
+++ b/kimap/createjob.h
@@ -1,53 +1,70 @@
/*
Copyright (c) 2009 Andras Mantia
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_CREATEJOB_H
#define KIMAP_CREATEJOB_H
#include "kimap_export.h"
#include "job.h"
namespace KIMAP {
class Session;
struct Message;
class CreateJobPrivate;
+/**
+ * Creates a new mailbox
+ *
+ * This job can only be run when the session is in the
+ * authenticated (or selected) state.
+ *
+ * This job will fail if the mailbox already exists.
+ */
class KIMAP_EXPORT CreateJob : public Job
{
Q_OBJECT
Q_DECLARE_PRIVATE(CreateJob)
friend class SessionPrivate;
public:
explicit CreateJob( Session *session );
virtual ~CreateJob();
+ /**
+ * Set the name of the new mailbox
+ *
+ * @param mailBox an (unquoted) identifier that does not correspond
+ * to an existing mailbox name
+ */
void setMailBox( const QString &mailBox );
+ /**
+ * The name of the mailbox that will be created
+ */
QString mailBox() const;
protected:
virtual void doStart();
};
}
#endif