summaryrefslogtreecommitdiffstats
path: root/kdecore/kuser.h
blob: be5834f09fd2f104b0b55d2ff3e292d1787660d7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
/*
 *  KUser - represent a user/account
 *  Copyright (C) 2002-2003 Tim Jansen <tim@tjansen.de>
 *  Copyright (C) 2003 Oswald Buddenhagen <ossi@kde.org>
 *  Copyright (C) 2004 Jan Schaefer <j_schaef@informatik.uni-kl.de>
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public License
 *  along with this library; see the file COPYING.LIB.  If not, write to
 *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 *  Boston, MA 02110-1301, USA.
 */
#ifndef KUSER_H
#define KUSER_H

#include "ksharedptr.h"

class KUserGroup;
class TQString;
class TQStringList;
class KUserPrivate;
struct passwd;
template <class T> class TQValueList;

/**
 * @short Represents a user on your system
 *
 * This class represents a user on your system. You can either get
 * information about the current user, of fetch information about
 * a user on the system. Instances of this class will be explicitly shared,
 * so copying objects is very cheap and you can safely pass objects by value.
 *
 * @author Tim Jansen <tim@tjansen.de>
 * @since 3.2
 */
class KDECORE_EXPORT KUser {

public:

  enum UIDMode { 
  	UseEffectiveUID, ///< Use the effective user id.
  	UseRealUserID    ///< Use the real user id.
  };

  /**
   * Creates an object that tqcontains information about the current user.
   * (as returned by getuid(2) or geteuid(2), taking $LOGNAME/$USER into
   * account).
   * @param mode if #UseEffectiveUID is passed the effective
   *             user is returned. 
   *        If #UseRealUserID is passed the real user will be
   *        returned. 
   *        The real UID will be different than the effective UID in setuid
   *        programs; in  
   *        such a case use the effective UID for checking permissions, and
   *        the real UID for displaying information about the user.
   */
  // XXX KDE4: Make this explicit
  KUser(UIDMode mode = UseEffectiveUID);

  /**
   * Creates an object for the user with the given user id.
   * If the user does not exist isValid() will return false.
   * @param uid the user id
   */
  // XXX KDE4: Make this explicit; give parameter as uid_t instead of "long"
  KUser(long uid);

  /**
   * Creates an object that tqcontains information about the user with the given
   * name. If the user does not exist isValid() will return false.
   *
   * @param name the name of the user
   */
  // XXX KDE4: Make this explicit
  KUser(const TQString& name);

  /**
   * Creates an object that tqcontains information about the user with the given
   * name. If the user does not exist isValid() will return false.
   *
   * @param name the name of the user
   */
  // XXX KDE4: Make this explicit
  KUser(const char *name);

  /**
   * Creates an object from a passwd structure.
   * If the pointer is null isValid() will return false.
   *
   * @param p the passwd structure to create the user from
   */
  // XXX KDE4: Make this explicit
  KUser(struct passwd *p);

  /**
   * Creates an object from another KUser object
   * @param user the user to create the new object from
   */
  KUser(const KUser & user);
  
  /**
   * Copies a user
   * @param user the user to copy
   * @return this object
   */
  KUser& operator =(const KUser& user);
  
  /**
   * Two KUser objects are equal if isValid() is true 
   * and the uid() are identical.
   */
  bool operator ==(const KUser& user) const;

  /**
   * Two KUser objects are not equal if either isValid() is
   * not true or uid() are not identical.
   */
  bool operator !=(const KUser &user) const;

  /**
   * Returns true if the user is valid. A KUser object can be invalid if 
   * you created it with an non-existing uid or name.
   * @return true if the user is valid
   */
  bool isValid() const;

  /**
   * Returns the user id of the user.
   * @return the id of the user or -1 if user is invalid
   */
  // XXX KDE4: Make this return uid_t
  long uid() const;


  /**
   * Returns the group id of the user.
   * @return the id of the group or -1 if user is invalid
   */
  // XXX KDE4: Make this return gid_t
  long gid() const;

  /**
   * Checks whether the user it the super user (root).
   * @return true if the user is root
   */
  bool isSuperUser() const;

  /**
   * The login name of the user.
   * @return the login name of the user or TQString::null if user is invalid 
   */
  TQString loginName() const;

  /**
   * The full name of the user.
   * @return the full name of the user or TQString::null if user is invalid
   */
  TQString fullName() const;

  /**
   * The user's room number.
   * @return the room number of the user or TQString::null if not set or the
   *         user is invalid 
   */
  TQString roomNumber() const;

  /**
   * The user's work phone.
   * @return the work phone of the user or TQString::null if not set or the
   *         user is invalid 
   */
  TQString workPhone() const;

  /**
   * The user's home phone.
   * @return the home phone of the user or TQString::null if not set or the
   *         user is invalid 
   */
  TQString homePhone() const;

  /**
   * The path to the user's home directory.
   * @return the home directory of the user or TQString::null if the
   *         user is invalid 
   */
  TQString homeDir() const;

  /**
   * The path to the user's login shell.
   * @return the login shell of the user or TQString::null if the
   *         user is invalid 
   */
  TQString shell() const;

  /**
   * Returns all groups of the user
   * @return all groups of the user
   */
  TQValueList<KUserGroup> groups() const;
  
  /**
   * Returns all group names of the user
   * @return all group names of the user
   */
  TQStringList groupNames() const;
  
  
  /**
   * Destructor.
   */
  ~KUser();

  /** 
   * Returns all users of the system.
   * @return all users of the system.
   */
  static TQValueList<KUser> allUsers();

  /** 
   * Returns all user names of the system.
   * @return all user names of the system.
   */
  static TQStringList allUserNames();

private:
  KSharedPtr<KUserPrivate> d;
  void fillPasswd(struct passwd* p);
  void fillName(const char* name);
};

class KUserGroupPrivate;

struct group;

/**
 * @short Represents a group on your system
 *
 * This class represents a group on your system. You can either get
 * information about the group of the current user, of fetch information about
 * a group on the system. Instances of this class will be explicitly shared,
 * so copying objects is very cheap and you can safely pass objects by value.
 *
 * @author Jan Schaefer <j_schaef@informatik.uni-kl.de>
 * @since 3.3
 */
class KDECORE_EXPORT KUserGroup {

public:

  /**
   * Create an object from the group of the current user.
   * @param mode if #KUser::UseEffectiveUID is passed the effective user
   *        will be used. If #KUser::UseRealUserID is passed the real user
   *        will be used. 
   *        The real UID will be different than the effective UID in setuid
   *        programs; in  such a case use the effective UID for checking
   *        permissions, and the real UID for displaying information about
   *        the group associated with the user.
   */
  explicit KUserGroup(KUser::UIDMode mode = KUser::UseEffectiveUID);
  
  /**
   * Create an object from a group id.
   * If the group does not exist, isValid() will return false.
   * @param gid the group id
   */
  // XXX KDE4: Give parameter as gid_t instead of "long"
  explicit KUserGroup(long gid);
  
  /**
   * Create an object from a group name.
   * If the group does not exist, isValid() will return false.
   * @param name the name of the group
   */
  explicit KUserGroup(const TQString& name);
  
  /**
   * Create an object from a group name.
   * If the group does not exist, isValid() will return false.
   * @param name the name of the group
   */
  explicit KUserGroup(const char *name);
  
  /**
   * Creates an object from a group structure.
   * If the pointer is null, isValid() will return false.
   * @param g the group structure to create the group from.
   */
  explicit KUserGroup(struct group *g);
  
  /**
   * Creates a new KUserGroup instance from another KUserGroup object
   * @param group the KUserGroup to copy
   */
  KUserGroup(const KUserGroup & group);
  
  /**
   * Copies a group
   * @param group the group that should be copied
   * @return this group
   */
  KUserGroup& operator =(const KUserGroup& group);
  
  /**
   * Two KUserGroup objects are equal if isValid() is true
   * and gid() are identical
   * @return true if the groups are identical
   */
  bool operator ==(const KUserGroup& group) const;
  
  /**
   * Two KUserGroup objects are not equal if either 
   * isValid() is not true or gid() are not identical
   * @return true if the groups are not identical
   */
  bool operator !=(const KUserGroup& group) const;
  
  /**
   * Returns wether the group is valid.
   * A KUserGroup object can be invalid if it is 
   * created with a non-existing gid or name.
   * @return true if the group is valid
   */
  bool isValid() const;
  
  /**
   * Returns the group id of the group.
   * @return the group id of the group or -1 if the group is invalid
   */
  // XXX KDE4: Return gid_t instead of "long"
  long gid() const;
  
  /**
   * The name of the group.
   * @return the name of the group
   */
  TQString name() const;
  
  /**
   * Returns a list of all users of the group.
   * @return a list of all users of the group
   */
  const TQValueList<KUser>& users() const;
  
  /**
   * Returns a list of all user login names of the group.
   * @return a list of all user login names of the group
   */
  TQStringList userNames() const;
  
  
  /**
   * Destructor.
   */
  ~KUserGroup(); 
  
  /**
   * Returns a list of all groups on this system
   */
  static TQValueList<KUserGroup> allGroups();
  
  /**
   * Returns a list of all group names on this system
   */
  static TQStringList allGroupNames();
  
private:
  KSharedPtr<KUserGroupPrivate> d;
  void fillGroup(struct group* g);
  void fillName(const char* name);
};


#endif