1/* This file is part of the KDE project
2 Copyright (C) 2005 - 2007 Till Adam <adam@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public 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
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KACL_H
21#define KACL_H
22
23
24#include <sys/types.h>
25#include <kio/global.h>
26
27#include <QtCore/QPair>
28#include <QtCore/QList>
29
30
31typedef QPair<QString, unsigned short> ACLUserPermissions;
32typedef QList<ACLUserPermissions> ACLUserPermissionsList;
33typedef QList<ACLUserPermissions>::iterator ACLUserPermissionsIterator;
34typedef QList<ACLUserPermissions>::const_iterator ACLUserPermissionsConstIterator;
35
36typedef QPair<QString, unsigned short> ACLGroupPermissions;
37typedef QList<ACLGroupPermissions> ACLGroupPermissionsList;
38typedef QList<ACLGroupPermissions>::iterator ACLGroupPermissionsIterator;
39typedef QList<ACLGroupPermissions>::const_iterator ACLGroupPermissionsConstIterator;
40
41/**
42 * The KACL class encapsulates a POSIX Access Control List. It follows the
43 * little standard that couldn't, 1003.1e/1003.2c, which died in draft status.
44 * @short a POSIX ACL encapsulation
45 * @author Till Adam <adam@kde.org>
46 */
47class KIO_EXPORT KACL
48{
49public:
50 /**
51 * Creates a new KACL from @p aclString. If the string is a valid acl
52 * string, isValid() will afterwards return true.
53 */
54 KACL( const QString & aclString );
55
56 /** Copy ctor */
57 KACL( const KACL& rhs );
58
59 /**
60 * Creates a new KACL from the basic permissions passed in @p basicPermissions.
61 * isValid() will return true, afterwards.
62 */
63 KACL( mode_t basicPermissions );
64
65 /**
66 * Creates an empty KACL. Until a valid acl string is set via setACL,
67 * isValid() will return false.
68 */
69 KACL();
70
71 virtual ~KACL();
72
73 KACL& operator=( const KACL& rhs );
74
75 bool operator==( const KACL& rhs ) const;
76
77 bool operator!=( const KACL& rhs ) const;
78
79 /**
80 * Returns whether the KACL object represents a valid acl.
81 * @return whether the KACL object represents a valid acl.
82 */
83 bool isValid() const;
84
85 /** The standard (non-extended) part of an ACL. These map directly to
86 * standard unix file permissions. Setting them will never make a valid
87 * ACL invalid. */
88
89 /** @return the owner's premissions entry */
90 unsigned short ownerPermissions() const;
91
92 /** Set the owner's permissions entry.
93 * @return success or failure */
94 bool setOwnerPermissions( unsigned short );
95
96 /** @return the owning group's premissions entry */
97 unsigned short owningGroupPermissions() const;
98
99 /** Set the owning group's permissions entry.
100 * @return success or failure */
101 bool setOwningGroupPermissions( unsigned short );
102
103 /** @return the premissions entry for others */
104 unsigned short othersPermissions() const;
105
106 /** Set the permissions entry for others.
107 * @return success or failure */
108 bool setOthersPermissions( unsigned short );
109
110 /** @return the basic (owner/group/others) part of the ACL as a mode_t */
111 mode_t basePermissions() const;
112
113 /** The interface to the extended ACL. This is a mask, permissions for
114 * n named users and permissions for m named groups. */
115
116 /**
117 * Return whether the ACL contains extended entries or can be expressed
118 * using only basic file permissions.
119 * @return whether the ACL contains extended entries */
120 bool isExtended() const;
121
122 /**
123 * Return the entry for the permissions mask if there is one and sets
124 * @p exists to true. If there is no such entry, @p exists is set to false.
125 * @return the permissions mask entry */
126 unsigned short maskPermissions( bool &exists ) const;
127
128 /** Set the permissions mask for the ACL. Permissions set for individual
129 * entries will be masked with this, such that their effective permissions
130 * are the result of the logical and of their entry and the mask.
131 * @return success or failure */
132 bool setMaskPermissions( unsigned short );
133
134 /**
135 * Access to the permissions entry for a named user, if such an entry
136 * exists. If @p exists is non-null, the boolean variable it points to
137 * is set to true if a matching entry exists and to false otherwise.
138 * @return the permissions for a user entry with the name in @p name */
139 unsigned short namedUserPermissions( const QString& name, bool *exists ) const;
140
141 /** Set the permissions for a user with the name @p name. Will fail
142 * if the user doesn't exist, in which case the ACL will be unchanged.
143 * @return success or failure. */
144 bool setNamedUserPermissions( const QString& name, unsigned short );
145
146 /** Returns the list of all group permission entries. Each entry consists
147 * of a name/permissions pair. This is a QPair, therefore access is provided
148 * via the .first and .next members.
149 * @return the list of all group permission entries. */
150 ACLUserPermissionsList allUserPermissions() const;
151
152 /** Replace the list of all user permissions with @p list. If one
153 * of the entries in the list does not exists, or setting of the ACL
154 * entry fails for any reason, the ACL will be left unchanged.
155 * @return success or failure */
156 bool setAllUserPermissions( const ACLUserPermissionsList &list );
157
158 /**
159 * Access to the permissions entry for a named group, if such an entry
160 * exists. If @p exists is non-null, the boolean variable it points to is
161 * set to true if a matching entry exists and to false otherwise.
162 * @return the permissions for a group with the name in @p name */
163 unsigned short namedGroupPermissions( const QString& name, bool *exists ) const;
164
165 /** Set the permissions for a group with the name @p name. Will fail
166 * if the group doesn't exist, in which case the ACL be unchanged.
167 * @return success or failure. */
168 bool setNamedGroupPermissions( const QString& name, unsigned short );
169
170 /** Returns the list of all group permission entries. Each entry consists
171 * of a name/permissions pair. This is a QPair, therefor access is provided
172 * via the .first and .next members.
173 * @return the list of all group permission entries. */
174
175 ACLGroupPermissionsList allGroupPermissions() const;
176 /** Replace the list of all user permissions with @p list. If one
177 * of the entries in the list does not exists, or setting of the ACL
178 * entry fails for any reason, the ACL will be left unchanged.
179 * @return success or failure */
180 bool setAllGroupPermissions( const ACLGroupPermissionsList & );
181
182 /** Sets the whole list from a string. If the string in @p aclStr represents
183 * a valid ACL, it will be set, otherwise the ACL remains unchanged.
184 * @return whether setting the ACL was successful. */
185 bool setACL( const QString &aclStr );
186
187 /** Return a string representation of the ACL.
188 * @return a string version of the ACL in the format compatible with libacl and
189 * POSIX 1003.1e. Implementations conforming to that standard should be able
190 * to take such strings as input. */
191 QString asString() const;
192
193protected:
194 virtual void virtual_hook( int id, void* data );
195private:
196 class KACLPrivate;
197 KACLPrivate* const d;
198 KIO_EXPORT friend QDataStream & operator<< ( QDataStream & s, const KACL & a );
199 KIO_EXPORT friend QDataStream & operator>> ( QDataStream & s, KACL & a );
200};
201
202KIO_EXPORT QDataStream & operator<< ( QDataStream & s, const KACL & a );
203KIO_EXPORT QDataStream & operator>> ( QDataStream & s, KACL & a );
204
205#endif
206