1/*
2 Copyright (c) 2009 Andras Mantia <amantia@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef KIMAP_GETACLJOB_H
21#define KIMAP_GETACLJOB_H
22
23#include "kimap_export.h"
24
25#include "acljobbase.h"
26
27namespace KIMAP {
28
29class Session;
30struct Message;
31class GetAclJobPrivate;
32
33/**
34 * Gets the ACL for a mailbox
35 *
36 * This job can only be run when the session is in the
37 * authenticated (or selected) state.
38 *
39 * The user must have the Acl::Admin permission
40 * on the mailbox for this job to succeed (see
41 * MyRightsJob).
42 *
43 * This job requires that the server supports the ACL
44 * capability, defined in
45 * <a href="http://www.apps.ietf.org/rfc/rfc4314.html">RFC 4314</a>.
46 *
47 * The meaning of identifiers depends on the server implementation,
48 * with the following restrictions:
49 *
50 * - "anyone" means any authenticated user, including anonymous
51 * - an identifier starting with a minus sign ('-') indicates
52 * "negative rights": rights that should be taken away from
53 * matching users
54 *
55 * Other than the above restrictions, ACL identifiers are usually
56 * IMAP usernames, but could potentially be group names as well.
57 *
58 * Note that negative rights override positive rights: if
59 * "fred" and "-fred" are both assigned the 'w' right, the
60 * user "fred" will not have the 'w' right.
61 */
62class KIMAP_EXPORT GetAclJob : public AclJobBase
63{
64 Q_OBJECT
65 Q_DECLARE_PRIVATE( GetAclJob )
66
67 friend class SessionPrivate;
68
69 public:
70 explicit GetAclJob( Session *session );
71 virtual ~GetAclJob();
72
73 /**
74 * The identifiers present in the ACL.
75 *
76 * This method will return an empty list if the job has
77 * not yet been run.
78 *
79 * See the GetAclJob documentation for an explanation of
80 * identifiers; in particular, identifiers starting with
81 * '-' specify negative rights.
82 */
83 QList<QByteArray> identifiers() const;
84 /**
85 * Check whether an identifier has a given right set
86 *
87 * The result of this method is undefined if the job has
88 * not yet completed.
89 *
90 * See the GetAclJob documentation for an explanation of
91 * identifiers; in particular, identifiers starting with
92 * '-' specify negative rights.
93 *
94 * Note that this will not tell you whether the net result
95 * of all the ACL entries means that a given user has
96 * a certain right.
97 *
98 * @param identifier the identifier to check the rights for
99 * @param right the right to check for
100 */
101 bool hasRightEnabled(const QByteArray &identifier, Acl::Right right) const;
102 /**
103 * Get the rights associated with an identifier.
104 *
105 * The result of this method is undefined if the job has
106 * not yet completed.
107 *
108 * See the GetAclJob documentation for an explanation of
109 * identifiers; in particular, identifiers starting with
110 * '-' specify negative rights.
111 *
112 * Note that this will not tell you the rights that a
113 * given user will have once all the ACL entries have
114 * been taken into account.
115 *
116 * @param identifier the identifier to check the rights for
117 */
118 Acl::Rights rights(const QByteArray &identifier) const;
119
120 /**
121 * Gets the full access control list.
122 *
123 * The result of this method is undefined if the job has
124 * not yet completed.
125 *
126 * See the GetAclJob documentation for an explanation of
127 * identifiers; in particular, identifiers starting with
128 * '-' specify negative rights.
129 */
130 QMap<QByteArray, Acl::Rights> allRights() const;
131
132 protected:
133 virtual void doStart();
134 virtual void handleResponse(const Message &response);
135
136};
137
138}
139
140#endif
141