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 | #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 | |
245 | private: |
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 | */ |
262 | class KDECORE_EXPORT KUserGroup { |
263 | |
264 | public: |
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 | |
384 | private: |
385 | class Private; |
386 | KSharedPtr<Private> d; |
387 | }; |
388 | |
389 | #endif |
390 | |