kdecore/util/kuser.h

   1 /*
   2  *  KUser - represent a user/account
   3  *  Copyright (C) 2002-2003 Tim Jansen <tim@tjansen.de>
   4  *  Copyright (C) 2003 Oswald Buddenhagen <ossi@kde.org>
   5  *  Copyright (C) 2004 Jan Schaefer <j_schaef@informatik.uni-kl.de>
   6  *
   7  *  This library is free software; you can redistribute it and/or
   8  *  modify it under the terms of the GNU Library General Public
   9  *  License as published by the Free Software Foundation; either
  10  *  version 2 of the License, or (at your option) any later version.
  11  *
  12  *  This library is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  *  Library General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU Library General Public License
  18  *  along with this library; see the file COPYING.LIB.  If not, write to
  19  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20  *  Boston, MA 02110-1301, USA.
  21  */
  22 #ifndef KUSER_H
  23 #define KUSER_H
  24
  25 #include <kdecore_export.h>
  26 #include <ksharedptr.h>
  27
  28 #include <QtCore/QVariant>
  29
  30 class KUserGroup;
  31 class QString;
  32 class QStringList;
  33 template <class T> class QList;
  34
  35 #ifdef Q_OS_WIN
  36 typedef void *K_UID;
  37 typedef void *K_GID;
  38 #else
  39 #include <sys/types.h>
  40 typedef uid_t K_UID;
  41 typedef gid_t K_GID;
  42 struct passwd;
  43 struct group;
  44 #endif
  45
  46
  47 /**
  48  * \class KUser kuser.h <KUser>
  49  *
  50  * @short Represents a user on your system
  51  *
  52  * This class represents a user on your system. You can either get
  53  * information about the current user, of fetch information about
  54  * a user on the system. Instances of this class will be explicitly shared,
  55  * so copying objects is very cheap and you can safely pass objects by value.
  56  *
  57  * @author Tim Jansen <tim@tjansen.de>
  58  */
  59 class KDECORE_EXPORT KUser {
  60
  61 public:
  62
  63   enum UIDMode {
  64         UseEffectiveUID, ///< Use the effective user id.
  65         UseRealUserID    ///< Use the real user id.
  66   };
  67
  68   /**
  69    * Creates an object that contains information about the current user.
  70    * (as returned by getuid(2) or geteuid(2), taking $LOGNAME/$USER into
  71    * account).
  72    * @param mode if #UseEffectiveUID is passed the effective
  73    *             user is returned.
  74    *        If #UseRealUserID is passed the real user will be
  75    *        returned.
  76    *        The real UID will be different than the effective UID in setuid
  77    *        programs; in
  78    *        such a case use the effective UID for checking permissions, and
  79    *        the real UID for displaying information about the user.
  80    */
  81   explicit KUser(UIDMode mode = UseEffectiveUID);
  82
  83   /**
  84    * Creates an object for the user with the given user id.
  85    * If the user does not exist isValid() will return false.
  86    * @param uid the user id
  87    */
  88   explicit KUser(K_UID uid);
  89
  90   /**
  91    * Creates an object that contains information about the user with the given
  92    * name. If the user does not exist isValid() will return false.
  93    *
  94    * @param name the name of the user
  95    */
  96   explicit KUser(const QString& name);
  97
  98   /**
  99    * Creates an object that contains information about the user with the given
 100    * name. If the user does not exist isValid() will return false.
 101    *
 102    * @param name the name of the user
 103    */
 104   explicit KUser(const char* name);
 105
 106 #ifndef Q_OS_WIN
 107   /**
 108    * Creates an object from a passwd structure.
 109    * If the pointer is null isValid() will return false.
 110    *
 111    * @param p the passwd structure to create the user from
 112    */
 113   explicit KUser(const passwd *p);
 114 #endif
 115
 116   /**
 117    * Creates an object from another KUser object
 118    * @param user the user to create the new object from
 119    */
 120   KUser(const KUser & user);
 121
 122   /**
 123    * Copies a user
 124    * @param user the user to copy
 125    * @return this object
 126    */
 127   KUser& operator =(const KUser& user);
 128
 129   /**
 130    * Two KUser objects are equal if the uid() are identical.
 131    * Invalid users never compare equal.
 132    */
 133   bool operator ==(const KUser& user) const;
 134
 135   /**
 136    * Two KUser objects are not equal if uid() are not identical.
 137    * Invalid users always compare unequal.
 138    */
 139   bool operator !=(const KUser &user) const;
 140
 141   /**
 142    * Returns true if the user is valid. A KUser object can be invalid if
 143    * you created it with an non-existing uid or name.
 144    * @return true if the user is valid
 145    */
 146   bool isValid() const;
 147
 148   /**
 149    * Returns the user id of the user.
 150    * @return the id of the user or -1 if user is invalid
 151    */
 152   K_UID uid() const;
 153
 154 #ifndef Q_OS_WIN
 155   /**
 156    * Returns the group id of the user.
 157    * @return the id of the group or -1 if user is invalid
 158    */
 159   K_GID gid() const;
 160 #endif
 161
 162   /**
 163    * Checks whether the user is the super user (root).
 164    * @return true if the user is root
 165    */
 166   bool isSuperUser() const;
 167
 168   /**
 169    * The login name of the user.
 170    * @return the login name of the user or QString() if user is invalid
 171    */
 172   QString loginName() const;
 173
 174   /**
 175    * The full name of the user.
 176    * @return the full name of the user or QString() if user is invalid
 177    * @deprecated use property(KUser::FullName) instead
 178    */
 179   KDE_DEPRECATED QString fullName() const;
 180
 181   /**
 182    * The path to the user's home directory.
 183    * @return the home directory of the user or QString() if the
 184    *         user is invalid
 185    */
 186   QString homeDir() const;
 187
 188   /**
 189    * The path to the user's face file.
 190    * @return the path to the user's face file or QString() if no
 191    *         face has been set
 192    */
 193   QString faceIconPath() const;
 194
 195   /**
 196    * The path to the user's login shell.
 197    * @return the login shell of the user or QString() if the
 198    *         user is invalid
 199    */
 200   QString shell() const;
 201
 202   /**
 203    * Returns all groups of the user
 204    * @return all groups of the user
 205    */
 206   QList<KUserGroup> groups() const;
 207
 208   /**
 209    * Returns all group names of the user
 210    * @return all group names of the user
 211    */
 212   QStringList groupNames() const;
 213
 214   enum UserProperty { FullName, RoomNumber, WorkPhone, HomePhone };
 215
 216   /**
 217    * Returns an extended property.
 218    *
 219    * Under Windows, @p RoomNumber, @p WorkPhone and @p HomePhone are unsupported.
 220    *
 221    * @return a QVariant with the value of the property or an invalid QVariant,
 222    *         if the property is not set
 223    */
 224   QVariant property(UserProperty which) const;
 225
 226   /**
 227    * Destructor.
 228    */
 229   ~KUser();
 230
 231   /**
 232    * Returns all users of the system.
 233    * @return all users of the system.
 234    */
 235   static QList<KUser> allUsers();
 236
 237   /**
 238    * Returns all user names of the system.
 239    * @return all user names of the system.
 240    */
 241   static QStringList allUserNames();
 242
 243 private:
 244   class Private;
 245   KSharedPtr<Private> d;
 246 };
 247
 248 /**
 249  * \class KUserGroup kuser.h <KUserGroup>
 250  *
 251  * @short Represents a group on your system
 252  *
 253  * This class represents a group on your system. You can either get
 254  * information about the group of the current user, of fetch information about
 255  * a group on the system. Instances of this class will be explicitly shared,
 256  * so copying objects is very cheap and you can safely pass objects by value.
 257  *
 258  * @author Jan Schaefer <j_schaef@informatik.uni-kl.de>
 259  */
 260 class KDECORE_EXPORT KUserGroup {
 261
 262 public:
 263
 264   /**
 265    * Create an object from a group name.
 266    * If the group does not exist, isValid() will return false.
 267    * @param name the name of the group
 268    */
 269   explicit KUserGroup(const QString& name);
 270
 271   /**
 272    * Create an object from a group name.
 273    * If the group does not exist, isValid() will return false.
 274    * @param name the name of the group
 275    */
 276   explicit KUserGroup(const char *name);
 277
 278 #ifndef Q_OS_WIN
 279   /**
 280    * Create an object from the group of the current user.
 281    * @param mode if #KUser::UseEffectiveUID is passed the effective user
 282    *        will be used. If #KUser::UseRealUserID is passed the real user
 283    *        will be used.
 284    *        The real UID will be different than the effective UID in setuid
 285    *        programs; in  such a case use the effective UID for checking
 286    *        permissions, and the real UID for displaying information about
 287    *        the group associated with the user.
 288    */
 289   explicit KUserGroup(KUser::UIDMode mode = KUser::UseEffectiveUID);
 290
 291   /**
 292    * Create an object from a group id.
 293    * If the group does not exist, isValid() will return false.
 294    * @param gid the group id
 295    */
 296   explicit KUserGroup(K_GID gid);
 297
 298   /**
 299    * Creates an object from a group structure.
 300    * If the pointer is null, isValid() will return false.
 301    * @param g the group structure to create the group from.
 302    */
 303   explicit KUserGroup(const group *g);
 304 #endif
 305
 306   /**
 307    * Creates a new KUserGroup instance from another KUserGroup object
 308    * @param group the KUserGroup to copy
 309    */
 310   KUserGroup(const KUserGroup & group);
 311
 312   /**
 313    * Copies a group
 314    * @param group the group that should be copied
 315    * @return this group
 316    */
 317   KUserGroup& operator =(const KUserGroup& group);
 318
 319   /**
 320    * Two KUserGroup objects are equal if their gid()s are identical.
 321    * Invalid groups never compare equal.
 322    * @return true if the groups are identical
 323    */
 324   bool operator ==(const KUserGroup& group) const;
 325
 326   /**
 327    * Two KUserGroup objects are not equal if their gid()s are not identical.
 328    * Invalid groups always compare unequal.
 329    * @return true if the groups are not identical
 330    */
 331   bool operator !=(const KUserGroup& group) const;
 332
 333   /**
 334    * Returns whether the group is valid.
 335    * A KUserGroup object can be invalid if it is
 336    * created with a non-existing gid or name.
 337    * @return true if the group is valid
 338    */
 339   bool isValid() const;
 340
 341 #ifndef Q_OS_WIN
 342   /**
 343    * Returns the group id of the group.
 344    * @return the group id of the group or -1 if the group is invalid
 345    */
 346   K_GID gid() const;
 347 #endif
 348
 349   /**
 350    * The name of the group.
 351    * @return the name of the group
 352    */
 353   QString name() const;
 354
 355   /**
 356    * Returns a list of all users of the group.
 357    * @return a list of all users of the group
 358    */
 359   QList<KUser> users() const;
 360
 361   /**
 362    * Returns a list of all user login names of the group.
 363    * @return a list of all user login names of the group
 364    */
 365   QStringList userNames() const;
 366
 367   /**
 368    * Destructor.
 369    */
 370   ~KUserGroup();
 371
 372   /**
 373    * Returns a list of all groups on this system
 374    */
 375   static QList<KUserGroup> allGroups();
 376
 377   /**
 378    * Returns a list of all group names on this system
 379    */
 380   static QStringList allGroupNames();
 381
 382 private:
 383   class Private;
 384   KSharedPtr<Private> d;
 385 };
 386
 387 #endif