KIO

kacl.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2005-2007 Till Adam <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KACL_H
9 #define KACL_H
10 
11 #include "kiocore_export.h"
12 #include <qplatformdefs.h>
13 
14 #include <QList>
15 #include <QPair>
16 
17 #include <memory>
18 
23 
28 
29 /**
30  * @class KACL kacl.h <KACL>
31  *
32  * The KACL class encapsulates a POSIX Access Control List. It follows the
33  * little standard that couldn't, 1003.1e/1003.2c, which died in draft status.
34  * @short a POSIX ACL encapsulation
35  * @author Till Adam <[email protected]>
36  */
37 class KIOCORE_EXPORT KACL
38 {
39 public:
40  /**
41  * Creates a new KACL from @p aclString. If the string is a valid acl
42  * string, isValid() will afterwards return true.
43  */
44  KACL(const QString &aclString);
45 
46  /** Copy ctor */
47  KACL(const KACL &rhs);
48 
49  /**
50  * Creates a new KACL from the basic permissions passed in @p basicPermissions.
51  * isValid() will return true, afterwards.
52  */
53  KACL(mode_t basicPermissions);
54 
55  /**
56  * Creates an empty KACL. Until a valid acl string is set via setACL,
57  * isValid() will return false.
58  */
59  KACL();
60 
61  virtual ~KACL();
62 
63  KACL &operator=(const KACL &rhs);
64 
65  bool operator==(const KACL &rhs) const;
66 
67  bool operator!=(const KACL &rhs) const;
68 
69  /**
70  * Returns whether the KACL object represents a valid acl.
71  * @return whether the KACL object represents a valid acl.
72  */
73  bool isValid() const;
74 
75  /** The standard (non-extended) part of an ACL. These map directly to
76  * standard unix file permissions. Setting them will never make a valid
77  * ACL invalid. */
78 
79  /** @return the owner's permissions entry */
80  unsigned short ownerPermissions() const;
81 
82  /** Set the owner's permissions entry.
83  * @return success or failure */
84  bool setOwnerPermissions(unsigned short);
85 
86  /** @return the owning group's permissions entry */
87  unsigned short owningGroupPermissions() const;
88 
89  /** Set the owning group's permissions entry.
90  * @return success or failure */
91  bool setOwningGroupPermissions(unsigned short);
92 
93  /** @return the permissions entry for others */
94  unsigned short othersPermissions() const;
95 
96  /** Set the permissions entry for others.
97  * @return success or failure */
98  bool setOthersPermissions(unsigned short);
99 
100  /** @return the basic (owner/group/others) part of the ACL as a mode_t */
101  mode_t basePermissions() const;
102 
103  /** The interface to the extended ACL. This is a mask, permissions for
104  * n named users and permissions for m named groups. */
105 
106  /**
107  * Return whether the ACL contains extended entries or can be expressed
108  * using only basic file permissions.
109  * @return whether the ACL contains extended entries */
110  bool isExtended() const;
111 
112  /**
113  * Return the entry for the permissions mask if there is one and sets
114  * @p exists to true. If there is no such entry, @p exists is set to false.
115  * @return the permissions mask entry */
116  unsigned short maskPermissions(bool &exists) const;
117 
118  /** Set the permissions mask for the ACL. Permissions set for individual
119  * entries will be masked with this, such that their effective permissions
120  * are the result of the logical and of their entry and the mask.
121  * @return success or failure */
122  bool setMaskPermissions(unsigned short);
123 
124  /**
125  * Access to the permissions entry for a named user, if such an entry
126  * exists. If @p exists is non-null, the boolean variable it points to
127  * is set to true if a matching entry exists and to false otherwise.
128  * @return the permissions for a user entry with the name in @p name */
129  unsigned short namedUserPermissions(const QString &name, bool *exists) const;
130 
131  /** Set the permissions for a user with the name @p name. Will fail
132  * if the user doesn't exist, in which case the ACL will be unchanged.
133  * @return success or failure. */
134  bool setNamedUserPermissions(const QString &name, unsigned short);
135 
136  /** Returns the list of all group permission entries. Each entry consists
137  * of a name/permissions pair. This is a QPair, therefore access is provided
138  * via the .first and .next members.
139  * @return the list of all group permission entries. */
140  ACLUserPermissionsList allUserPermissions() const;
141 
142  /** Replace the list of all user permissions with @p list. If one
143  * of the entries in the list does not exists, or setting of the ACL
144  * entry fails for any reason, the ACL will be left unchanged.
145  * @return success or failure */
146  bool setAllUserPermissions(const ACLUserPermissionsList &list);
147 
148  /**
149  * Access to the permissions entry for a named group, if such an entry
150  * exists. If @p exists is non-null, the boolean variable it points to is
151  * set to true if a matching entry exists and to false otherwise.
152  * @return the permissions for a group with the name in @p name */
153  unsigned short namedGroupPermissions(const QString &name, bool *exists) const;
154 
155  /** Set the permissions for a group with the name @p name. Will fail
156  * if the group doesn't exist, in which case the ACL be unchanged.
157  * @return success or failure. */
158  bool setNamedGroupPermissions(const QString &name, unsigned short);
159 
160  /** Returns the list of all group permission entries. Each entry consists
161  * of a name/permissions pair. This is a QPair, therefore access is provided
162  * via the .first and .next members.
163  * @return the list of all group permission entries. */
164 
165  ACLGroupPermissionsList allGroupPermissions() const;
166  /** Replace the list of all user permissions with @p list. If one
167  * of the entries in the list does not exists, or setting of the ACL
168  * entry fails for any reason, the ACL will be left unchanged.
169  * @return success or failure */
170  bool setAllGroupPermissions(const ACLGroupPermissionsList &);
171 
172  /** Sets the whole list from a string. If the string in @p aclStr represents
173  * a valid ACL, it will be set, otherwise the ACL remains unchanged.
174  * @return whether setting the ACL was successful. */
175  bool setACL(const QString &aclStr);
176 
177  /** Return a string representation of the ACL.
178  * @return a string version of the ACL in the format compatible with libacl and
179  * POSIX 1003.1e. Implementations conforming to that standard should be able
180  * to take such strings as input. */
181  QString asString() const;
182 
183 protected:
184  virtual void virtual_hook(int id, void *data);
185 
186 private:
187  class KACLPrivate;
188  std::unique_ptr<KACLPrivate> const d;
189  KIOCORE_EXPORT friend QDataStream &operator<<(QDataStream &s, const KACL &a);
190  KIOCORE_EXPORT friend QDataStream &operator>>(QDataStream &s, KACL &a);
191 };
192 
193 KIOCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KACL &a);
194 KIOCORE_EXPORT QDataStream &operator>>(QDataStream &s, KACL &a);
195 
196 #endif
QDataStream & operator>>(QDataStream &in, KDateTime::Spec &spec)
const QLatin1String name
QDataStream & operator<<(QDataStream &out, const KDateTime::Spec &spec)
The KACL class encapsulates a POSIX Access Control List.
Definition: kacl.h:37
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Jan 18 2022 22:53:45 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.