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
30class KUserGroup;
31class QString;
32class QStringList;
33template <class T> class QList;
34
35#ifdef Q_OS_WIN
36typedef void *K_UID;
37typedef void *K_GID;
38#else
39#include <sys/types.h>
40typedef uid_t K_UID;
41typedef gid_t K_GID;
42struct passwd;
43struct 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 */
59class KDECORE_EXPORT KUser {
60
61public:
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#ifndef KDE_NO_DEPRECATED
180 KDE_DEPRECATED QString fullName() const;
181#endif
182
183 /**
184 * The path to the user's home directory.
185 * @return the home directory of the user or QString() if the
186 * user is invalid
187 */
188 QString homeDir() const;
189
190 /**
191 * The path to the user's face file.
192 * @return the path to the user's face file or QString() if no
193 * face has been set
194 */
195 QString faceIconPath() const;
196
197 /**
198 * The path to the user's login shell.
199 * @return the login shell of the user or QString() if the
200 * user is invalid
201 */
202 QString shell() const;
203
204 /**
205 * Returns all groups of the user
206 * @return all groups of the user
207 */
208 QList<KUserGroup> groups() const;
209
210 /**
211 * Returns all group names of the user
212 * @return all group names of the user
213 */
214 QStringList groupNames() const;
215
216 enum UserProperty { FullName, RoomNumber, WorkPhone, HomePhone };
217
218 /**
219 * Returns an extended property.
220 *
221 * Under Windows, @p RoomNumber, @p WorkPhone and @p HomePhone are unsupported.
222 *
223 * @return a QVariant with the value of the property or an invalid QVariant,
224 * if the property is not set
225 */
226 QVariant property(UserProperty which) const;
227
228 /**
229 * Destructor.
230 */
231 ~KUser();
232
233 /**
234 * Returns all users of the system.
235 * @return all users of the system.
236 */
237 static QList<KUser> allUsers();
238
239 /**
240 * Returns all user names of the system.
241 * @return all user names of the system.
242 */
243 static QStringList allUserNames();
244
245private:
246 class Private;
247 KSharedPtr<Private> d;
248};
249
250/**
251 * \class KUserGroup kuser.h <KUserGroup>
252 *
253 * @short Represents a group on your system
254 *
255 * This class represents a group on your system. You can either get
256 * information about the group of the current user, of fetch information about
257 * a group on the system. Instances of this class will be explicitly shared,
258 * so copying objects is very cheap and you can safely pass objects by value.
259 *
260 * @author Jan Schaefer <j_schaef@informatik.uni-kl.de>
261 */
262class KDECORE_EXPORT KUserGroup {
263
264public:
265
266 /**
267 * Create an object from a group name.
268 * If the group does not exist, isValid() will return false.
269 * @param name the name of the group
270 */
271 explicit KUserGroup(const QString& name);
272
273 /**
274 * Create an object from a group name.
275 * If the group does not exist, isValid() will return false.
276 * @param name the name of the group
277 */
278 explicit KUserGroup(const char *name);
279
280#ifndef Q_OS_WIN
281 /**
282 * Create an object from the group of the current user.
283 * @param mode if #KUser::UseEffectiveUID is passed the effective user
284 * will be used. If #KUser::UseRealUserID is passed the real user
285 * will be used.
286 * The real UID will be different than the effective UID in setuid
287 * programs; in such a case use the effective UID for checking
288 * permissions, and the real UID for displaying information about
289 * the group associated with the user.
290 */
291 explicit KUserGroup(KUser::UIDMode mode = KUser::UseEffectiveUID);
292
293 /**
294 * Create an object from a group id.
295 * If the group does not exist, isValid() will return false.
296 * @param gid the group id
297 */
298 explicit KUserGroup(K_GID gid);
299
300 /**
301 * Creates an object from a group structure.
302 * If the pointer is null, isValid() will return false.
303 * @param g the group structure to create the group from.
304 */
305 explicit KUserGroup(const group *g);
306#endif
307
308 /**
309 * Creates a new KUserGroup instance from another KUserGroup object
310 * @param group the KUserGroup to copy
311 */
312 KUserGroup(const KUserGroup & group);
313
314 /**
315 * Copies a group
316 * @param group the group that should be copied
317 * @return this group
318 */
319 KUserGroup& operator =(const KUserGroup& group);
320
321 /**
322 * Two KUserGroup objects are equal if their gid()s are identical.
323 * Invalid groups never compare equal.
324 * @return true if the groups are identical
325 */
326 bool operator ==(const KUserGroup& group) const;
327
328 /**
329 * Two KUserGroup objects are not equal if their gid()s are not identical.
330 * Invalid groups always compare unequal.
331 * @return true if the groups are not identical
332 */
333 bool operator !=(const KUserGroup& group) const;
334
335 /**
336 * Returns whether the group is valid.
337 * A KUserGroup object can be invalid if it is
338 * created with a non-existing gid or name.
339 * @return true if the group is valid
340 */
341 bool isValid() const;
342
343#ifndef Q_OS_WIN
344 /**
345 * Returns the group id of the group.
346 * @return the group id of the group or -1 if the group is invalid
347 */
348 K_GID gid() const;
349#endif
350
351 /**
352 * The name of the group.
353 * @return the name of the group
354 */
355 QString name() const;
356
357 /**
358 * Returns a list of all users of the group.
359 * @return a list of all users of the group
360 */
361 QList<KUser> users() const;
362
363 /**
364 * Returns a list of all user login names of the group.
365 * @return a list of all user login names of the group
366 */
367 QStringList userNames() const;
368
369 /**
370 * Destructor.
371 */
372 ~KUserGroup();
373
374 /**
375 * Returns a list of all groups on this system
376 */
377 static QList<KUserGroup> allGroups();
378
379 /**
380 * Returns a list of all group names on this system
381 */
382 static QStringList allGroupNames();
383
384private:
385 class Private;
386 KSharedPtr<Private> d;
387};
388
389#endif
390