kio/kio/kacl.h

   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
  31 typedef QPair<QString, unsigned short> ACLUserPermissions;
  32 typedef QList<ACLUserPermissions> ACLUserPermissionsList;
  33 typedef QList<ACLUserPermissions>::iterator ACLUserPermissionsIterator;
  34 typedef QList<ACLUserPermissions>::const_iterator ACLUserPermissionsConstIterator;
  35
  36 typedef QPair<QString, unsigned short> ACLGroupPermissions;
  37 typedef QList<ACLGroupPermissions> ACLGroupPermissionsList;
  38 typedef QList<ACLGroupPermissions>::iterator ACLGroupPermissionsIterator;
  39 typedef 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  */
  47 class KIO_EXPORT KACL
  48 {
  49 public:
  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
 193 protected:
 194   virtual void virtual_hook( int id, void* data );
 195 private:
 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
 202 KIO_EXPORT QDataStream & operator<< ( QDataStream & s, const KACL & a );
 203 KIO_EXPORT QDataStream & operator>> ( QDataStream & s, KACL & a );
 204
 205 #endif