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