diff --git a/kimap/appendjob.h b/kimap/appendjob.h index e8e33e122..9fdc2bd67 100644 --- a/kimap/appendjob.h +++ b/kimap/appendjob.h @@ -1,108 +1,111 @@ /* 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. + * + * If the server supports ACLs, the user will need the + * Acl::Insert right on the mailbox. */ 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/closejob.h b/kimap/closejob.h index a2347f00c..3cadc72e5 100644 --- a/kimap/closejob.h +++ b/kimap/closejob.h @@ -1,68 +1,69 @@ /* 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. + * state, or if the server supports ACLs and the user does not + * have the Acl::Expunge right on the mailbox. */ 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 a80076aaa..5e75fdcfd 100644 --- a/kimap/copyjob.h +++ b/kimap/copyjob.h @@ -1,120 +1,127 @@ /* 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. + * + * If the server supports ACLs, the user will need the + * Acl::Insert right on the target mailbox. + * In order to preserve message flags, the user may also need + * some combination of Acl::DeleteMessage, + * Acl::KeepSeen and Acl::Write on the + * target mailbox. */ 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 a494480db..daab4787f 100644 --- a/kimap/createjob.h +++ b/kimap/createjob.h @@ -1,70 +1,76 @@ /* 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. + * + * If the server supports ACLs, the user must have the + * Acl::CreateMailbox permission on the parent + * mailbox. Note that what is meant by "parent mailbox" + * depends on the server: . and / are typical hierachy + * delimiters. */ 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 diff --git a/kimap/deleteacljob.h b/kimap/deleteacljob.h index 684647b77..0f06055a7 100644 --- a/kimap/deleteacljob.h +++ b/kimap/deleteacljob.h @@ -1,74 +1,74 @@ /* 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_DELETEACLJOB_H #define KIMAP_DELETEACLJOB_H #include "kimap_export.h" #include "acljobbase.h" namespace KIMAP { class Session; struct Message; class DeleteAclJobPrivate; /** * Removes an identifier from the ACL of a mailbox. * - * The user must have the Acl::Right::Admin permission - * on the mailbox for this job to succeed (see - * MyRightsJob). - * * This job can only be run when the session is in the * authenticated (or selected) state. * + * The user must have the Acl::Admin permission + * on the mailbox for this job to succeed (see + * MyRightsJob). + * * This job requires that the server supports the ACL * capability, defined in * RFC 4314. */ class KIMAP_EXPORT DeleteAclJob : public AclJobBase { Q_OBJECT Q_DECLARE_PRIVATE(DeleteAclJob) friend class SessionPrivate; public: explicit DeleteAclJob( Session *session ); virtual ~DeleteAclJob(); /** * Sets the identifier to remove */ void setIdentifier( const QByteArray &identifier ); /** * The identifier that will be removed */ QByteArray identifier(); protected: virtual void doStart(); }; } #endif diff --git a/kimap/deletejob.h b/kimap/deletejob.h index fb773175b..2876a90e5 100644 --- a/kimap/deletejob.h +++ b/kimap/deletejob.h @@ -1,52 +1,72 @@ /* 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_DELETEJOB_H #define KIMAP_DELETEJOB_H #include "kimap_export.h" #include "job.h" namespace KIMAP { class Session; class DeleteJobPrivate; +/** + * Delete a mailbox + * + * Note that some servers will refuse to delete a + * mailbox unless it is empty (ie: all mails have + * had their \Deleted flag set, and then the + * mailbox has been expunged). + * + * This job can only be run when the session is in the + * authenticated (or selected) state. + * + * If the server supports ACLs, you will need the + * Acl::DeleteMailbox right on the mailbox. + */ class KIMAP_EXPORT DeleteJob : public Job { Q_OBJECT Q_DECLARE_PRIVATE(DeleteJob) friend class SessionPrivate; public: explicit DeleteJob( Session *session ); virtual ~DeleteJob(); + /** + * Set the mailbox to delete. + */ void setMailBox( const QString &mailBox ); + /** + * The mailbox that will be deleted. + */ QString mailBox() const; protected: virtual void doStart(); }; } #endif diff --git a/kimap/expungejob.h b/kimap/expungejob.h index 7f91eac83..9862f5973 100644 --- a/kimap/expungejob.h +++ b/kimap/expungejob.h @@ -1,51 +1,63 @@ /* 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_EXPUNGEJOB_H #define KIMAP_EXPUNGEJOB_H #include "kimap_export.h" #include "job.h" namespace KIMAP { class Session; struct Message; class ExpungeJobPrivate; +/** + * Expunges the deleted messages in the selected mailbox. + * + * This permanently removes any messages that have the + * \Deleted flag set in the selected mailbox. + * + * This job can only be run when the session is in the + * selected state. + * + * If the server supports ACLs, the user will need the + * Acl::Expunge right on the mailbox. + */ class KIMAP_EXPORT ExpungeJob : public Job { Q_OBJECT Q_DECLARE_PRIVATE(ExpungeJob) friend class SessionPrivate; public: explicit ExpungeJob( Session *session ); virtual ~ExpungeJob(); protected: virtual void doStart(); virtual void handleResponse(const Message &response); }; } #endif diff --git a/kimap/fetchjob.h b/kimap/fetchjob.h index d44ee7b23..ac2543d5d 100644 --- a/kimap/fetchjob.h +++ b/kimap/fetchjob.h @@ -1,102 +1,312 @@ /* 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_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" #include namespace KIMAP { class Session; struct Message; class FetchJobPrivate; typedef boost::shared_ptr ContentPtr; typedef QMap MessageParts; typedef boost::shared_ptr MessagePtr; typedef QList MessageFlags; +/** + * 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. + */ struct FetchScope { - QList parts; // used only if mode == Headers or Content - enum Mode {Headers, Flags, Structure, Content, Full} mode; + /** + * 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 parts; + /** + * 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 + } mode; }; 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; + /** + * All the messages that have been received. + * + * This may be empty, depending on the scope of the fetch. + * + * @return a map from message sequence numbers to message contents (including headers) + */ QMap messages() const; + /** + * All the parts that have been received. + * + * Empty unless parts were specified in the scope. + * + * @return a map from message sequence numbers to message part collections + */ QMap parts() const; + /** + * All the flags that have been received. + * + * This may be empty, depending on the scope of the fetch. + * + * @return a map from message sequence numbers to message flags + */ QMap flags() const; + /** + * All the message sizes that have been received. + * + * This may be empty, depending on the scope of the fetch. + * + * @return a map from message sequence numbers to message sizes + * (sizes are in octets and refer to the transfer encoding of + * the message) + */ QMap sizes() const; + /** + * All the message UIDs that have been received. + * + * This will be populated with all the messages that data was + * fetched for. + * + * @return a map from message sequence numbers to message UIDs + */ QMap uids() 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 + */ void headersReceived( const QString &mailBox, const QMap &uids, const QMap &sizes, const QMap &flags, const QMap &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 + */ void messagesReceived( const QString &mailBox, const QMap &uids, const QMap &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 + */ void partsReceived( const QString &mailBox, const QMap &uids, const QMap &parts ); protected: virtual void doStart(); virtual void handleResponse(const Message &response); private: Q_PRIVATE_SLOT( d_func(), void emitPendings() ) }; } #endif diff --git a/kimap/getacljob.h b/kimap/getacljob.h index 93fdd65d7..dd652d20c 100644 --- a/kimap/getacljob.h +++ b/kimap/getacljob.h @@ -1,141 +1,141 @@ /* 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_GETACLJOB_H #define KIMAP_GETACLJOB_H #include "kimap_export.h" #include "acljobbase.h" namespace KIMAP { class Session; struct Message; class GetAclJobPrivate; /** * Gets the ACL for a mailbox * - * The user must have the Acl::Right::Admin permission - * on the mailbox for this job to succeed (see - * MyRightsJob). - * * This job can only be run when the session is in the * authenticated (or selected) state. * + * The user must have the Acl::Admin permission + * on the mailbox for this job to succeed (see + * MyRightsJob). + * * This job requires that the server supports the ACL * capability, defined in * RFC 4314. * * The meaning of identifiers depends on the server implementation, * with the following restrictions: * * - "anyone" means any authenticated user, including anonymous * - an identifier starting with a minus sign ('-') indicates * "negative rights": rights that should be taken away from * matching users * * Other than the above restrictions, ACL identifiers are usually * IMAP usernames, but could potentially be group names as well. * * Note that negative rights override positive rights: if * "fred" and "-fred" are both assigned the 'w' right, the * user "fred" will not have the 'w' right. */ class KIMAP_EXPORT GetAclJob : public AclJobBase { Q_OBJECT Q_DECLARE_PRIVATE(GetAclJob) friend class SessionPrivate; public: explicit GetAclJob( Session *session ); virtual ~GetAclJob(); /** * The identifiers present in the ACL. * * This method will return an empty list if the job has * not yet been run. * * See the GetAclJob documentation for an explanation of * identifiers; in particular, identifiers starting with * '-' specify negative rights. */ QList identifiers() const; /** * Check whether an identifier has a given right set * * The result of this method is undefined if the job has * not yet completed. * * See the GetAclJob documentation for an explanation of * identifiers; in particular, identifiers starting with * '-' specify negative rights. * * Note that this will not tell you whether the net result * of all the ACL entries means that a given user has * a certain right. * * @param identifier the identifier to check the rights for * @param right the right to check for */ bool hasRightEnabled(const QByteArray &identifier, Acl::Right right) const; /** * Get the rights associated with an identifier. * * The result of this method is undefined if the job has * not yet completed. * * See the GetAclJob documentation for an explanation of * identifiers; in particular, identifiers starting with * '-' specify negative rights. * * Note that this will not tell you the rights that a * given user will have once all the ACL entries have * been taken into account. * * @param identifier the identifier to check the rights for */ Acl::Rights rights(const QByteArray &identifier) const; /** * Gets the full access control list. * * The result of this method is undefined if the job has * not yet completed. * * See the GetAclJob documentation for an explanation of * identifiers; in particular, identifiers starting with * '-' specify negative rights. */ QMap allRights() const; protected: virtual void doStart(); virtual void handleResponse(const Message &response); }; } #endif diff --git a/kimap/listrightsjob.h b/kimap/listrightsjob.h index 53acf2773..ed4850d9c 100644 --- a/kimap/listrightsjob.h +++ b/kimap/listrightsjob.h @@ -1,122 +1,122 @@ /* 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_LISTRIGHTSJOB_H #define KIMAP_LISTRIGHTSJOB_H #include "kimap_export.h" #include "acljobbase.h" namespace KIMAP { class Session; struct Message; class ListRightsJobPrivate; /** * Lists the possible and automatic rights for * an identifier on a mailbox * - * The user must have the Acl::Right::Admin permission - * on the mailbox for this job to succeed (see - * MyRightsJob). - * * This job can only be run when the session is in the * authenticated (or selected) state. * + * The user must have the Acl::Admin permission + * on the mailbox for this job to succeed (see + * MyRightsJob). + * * This job requires that the server supports the ACL * capability, defined in * RFC 4314. */ class KIMAP_EXPORT ListRightsJob : public AclJobBase { Q_OBJECT Q_DECLARE_PRIVATE(ListRightsJob) friend class SessionPrivate; public: explicit ListRightsJob( Session *session ); virtual ~ListRightsJob(); /** * Sets the identifier that should be looked up * * The meaning of identifiers depends on the server implementation, * with the following restrictions: * * - "anyone" means any authenticated user, including anonymous * - an identifier starting with a minus sign ('-') indicates * "negative rights": rights that should be taken away from * matching users * * Other than the above restrictions, ACL identifiers are usually * IMAP usernames, but could potentially be group names as well. * * Note that negative rights override positive rights: if * "fred" and "-fred" are both assigned the 'w' right, the * user "fred" will not have the 'w' right. * * @param identifier the identifier to list the rights for */ void setIdentifier( const QByteArray &identifier ); /** * The identifier that will be looked up */ QByteArray identifier(); /** * The rights that will always be assigned to the identifier, * regardless of the access control list. * * For example, under the UNIX permission model, the owner - * of a mailbox will always have the Acl::Right::Admin right. + * of a mailbox will always have the Acl::Admin right. */ Acl::Rights defaultRights(); /** * The rights it is possible to assign to the identifier. * * The rights are grouped by those that are tied together. * For each set of rights in the returned list, either all * or none of those rights may be set, but not only some of * them. * * For example, under the UNIX permission model, the following * rights are all controlled by the "write" flag, and hence * must either all be set or all be not set: - * - Acl::Right::KeepSeen - * - Acl::Right::Write - * - Acl::Right::Insert - * - Acl::Right::DeleteMessage - * - Acl::Right::Expunge + * - Acl::KeepSeen + * - Acl::Write + * - Acl::Insert + * - Acl::DeleteMessage + * - Acl::Expunge */ QList possibleRights(); protected: virtual void doStart(); virtual void handleResponse(const Message &response); }; } #endif diff --git a/kimap/myrightsjob.h b/kimap/myrightsjob.h index e74b43ae6..4e57d0e3b 100644 --- a/kimap/myrightsjob.h +++ b/kimap/myrightsjob.h @@ -1,93 +1,93 @@ /* 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_MYRIGHTSJOB_H #define KIMAP_MYRIGHTSJOB_H #include "kimap_export.h" #include "acljobbase.h" namespace KIMAP { class Session; struct Message; class MyRightsJobPrivate; /** * Determine the rights the currently-logged-in user * has on the current mailbox. * * This should take into account the full access control * list. * - * The current user must have one of the following rights - * on the mailbox for this job to succeed: - * - Acl::Right::Lookup - * - Acl::Right::Read - * - Acl::Right::Insert - * - Acl::Right::CreateMailbox - * - Acl::Right::DeleteMailbox - * - Acl::Right::Admin - * * This job can only be run when the session is in the * authenticated (or selected) state. * + * The current user must have one of the following rights + * on the mailbox for this job to succeed: + * - Acl::Lookup + * - Acl::Read + * - Acl::Insert + * - Acl::CreateMailbox + * - Acl::DeleteMailbox + * - Acl::Admin + * * This job requires that the server supports the ACL * capability, defined in * RFC 4314. */ class KIMAP_EXPORT MyRightsJob : public AclJobBase { Q_OBJECT Q_DECLARE_PRIVATE(MyRightsJob) friend class SessionPrivate; public: explicit MyRightsJob( Session *session ); virtual ~MyRightsJob(); /** * Check whether the current user has the a particular right * on the mailbox. * * The result of this method is undefined if the job has * not yet completed. * * @param right the right to check for */ bool hasRightEnabled(Acl::Right right); /** * Get the rights for the current user on the mailbox. * * The result of this method is undefined if the job has * not yet completed. */ Acl::Rights rights(); protected: virtual void doStart(); virtual void handleResponse(const Message &response); }; } #endif