GumUser

GumUser — provides interface for managing user's account

Synopsis

#include <gum/gum-user.h>

struct              GumUser;
void                (*GumUserCb)                        (GumUser *user,
                                                         const GError *error,
                                                         gpointer user_data);
struct              GumUserClass;
gboolean            gum_user_add                        (GumUser *self,
                                                         GumUserCb callback,
                                                         gpointer user_data);
gboolean            gum_user_add_sync                   (GumUser *self);
GumUser *           gum_user_create                     (GumUserCb callback,
                                                         gpointer user_data);
GumUser *           gum_user_create_sync                ();
gboolean            gum_user_delete                     (GumUser *self,
                                                         gboolean rem_home_dir,
                                                         GumUserCb callback,
                                                         gpointer user_data);
gboolean            gum_user_delete_sync                (GumUser *self,
                                                         gboolean rem_home_dir);
GumUser *           gum_user_get                        (uid_t uid,
                                                         GumUserCb callback,
                                                         gpointer user_data);
GumUser *           gum_user_get_by_name                (const gchar *username,
                                                         GumUserCb callback,
                                                         gpointer user_data);
GumUser *           gum_user_get_by_name_sync           (const gchar *username);
GumUser *           gum_user_get_sync                   (uid_t uid);
gboolean            gum_user_update                     (GumUser *self,
                                                         GumUserCb callback,
                                                         gpointer user_data);
gboolean            gum_user_update_sync                (GumUser *self);

Object Hierarchy

  GObject
   +----GumUser

Properties

  "gid"                      guint                 : Read
  "homedir"                  gchar*                : Read / Write
  "homephone"                gchar*                : Read / Write
  "nickname"                 gchar*                : Read / Write
  "office"                   gchar*                : Read / Write
  "officephone"              gchar*                : Read / Write
  "realname"                 gchar*                : Read / Write
  "secret"                   gchar*                : Read / Write
  "shell"                    gchar*                : Read / Write
  "uid"                      guint                 : Read
  "username"                 gchar*                : Read / Write
  "usertype"                 guint                 : Read / Write

Description

GumUser provides interface for adding, removing and updating user accounts. User's information can also be retrieved using this interface. Only privileged user can access the interface when system-bus is used for communication with the user management daemon.

Following code snippet demonstrates how to create a new remote user object: 

 GumUser *user = NULL;

 user = gum_user_create_sync ();

 // use the object

 // destroy the object
 g_object_unref (user);

Similarly, new user can be added as: 

 GumUser *user = NULL;
 gboolean rval = FALSE;

 user = gum_user_create_sync ();

 // set user properties
 g_object_set (G_OBJECT (user), "username", "user1", "secret", "123456",
  "usertype", GUM_USERTYPE_NORMAL, NULL);

 // add user
 rval = gum_user_add_sync (user);

 // destroy the object
 g_object_unref (user);

For more details, see example implementation here: gum-utils

Details

struct GumUser

struct GumUser;

Opaque structure for the object.

GumUserCb ()

void                (*GumUserCb)                        (GumUser *user,
                                                         const GError *error,
                                                         gpointer user_data);

GumUserCb defines the callback which is used when user object is created, added, deleted or updated.

user :

 GumUser object which is used in the request. [transfer none]

error :

 GError object. In case of error, error will be non-NULL. [transfer none]

user_data :

 user data passed onto the request

struct GumUserClass

struct GumUserClass {
    GObjectClass parent_class;
};

Opaque structure for the class.

GObjectClass parent_class;

 parent class object

gum_user_add ()

gboolean            gum_user_add                        (GumUser *self,
                                                         GumUserCb callback,
                                                         gpointer user_data);

This method adds the user over the DBus asynchronously. Callback is used to notify when the user is added.

self :

 GumUser object to be added; object should have either valid "username" or "nickname" in addition to valid "usertype".

callback :

 GumUserCb to be invoked when user is added

user_data :

 user data

Returns :

 returns TRUE if the request has been pushed and is waiting for the response, FALSE otherwise. No callback is triggered, in case the function returns FALSE.

gum_user_add_sync ()

gboolean            gum_user_add_sync                   (GumUser *self);

This method adds the user over the DBus synchronously.

self :

 GumUser object to be added; object should have either valid "username" or "nickname" in addition to valid "usertype".

Returns :

 returns TRUE if successful, FALSE otherwise.

gum_user_create ()

GumUser *           gum_user_create                     (GumUserCb callback,
                                                         gpointer user_data);

This method creates a new remote user object over the DBus asynchronously. Callback is used to notify when the remote object is fully created and accessible.

callback :

 GumUserCb to be invoked when new user object is created

user_data :

 user data

Returns :

 GumUser newly created object. [transfer full]

gum_user_create_sync ()

GumUser *           gum_user_create_sync                ();

This method creates a new remote user object over the DBus synchronously.

Returns :

 GumUser newly created object. [transfer full]

gum_user_delete ()

gboolean            gum_user_delete                     (GumUser *self,
                                                         gboolean rem_home_dir,
                                                         GumUserCb callback,
                                                         gpointer user_data);

This method deletes the user over the DBus asynchronously. Callback is used to notify when the user is deleted.

self :

 GumUser object to be deleted; object should have valid "uid" property.

rem_home_dir :

 deletes home directory of the user if set to TRUE

callback :

 GumUserCb to be invoked when user is deleted

user_data :

 user data

Returns :

 returns TRUE if the request has been pushed and is waiting for the response, FALSE otherwise. No callback is triggered, in case the function returns FALSE.

gum_user_delete_sync ()

gboolean            gum_user_delete_sync                (GumUser *self,
                                                         gboolean rem_home_dir);

This method deletes the user over the DBus synchronously.

self :

 GumUser object to be deleted; object should have valid "uid" property.

rem_home_dir :

 deletes home directory of the user if set to TRUE

Returns :

 returns TRUE if successful, FALSE otherwise.

gum_user_get ()

GumUser *           gum_user_get                        (uid_t uid,
                                                         GumUserCb callback,
                                                         gpointer user_data);

This method gets the user object attached to uid over the DBus asynchronously. Callback is used to notify when the remote object is fully created and accessible.

uid :

 user id for the user

callback :

 GumUserCb to be invoked when user object is fetched

user_data :

 user data

Returns :

 GumUser object. [transfer full]

gum_user_get_by_name ()

GumUser *           gum_user_get_by_name                (const gchar *username,
                                                         GumUserCb callback,
                                                         gpointer user_data);

This method gets the user object attached to username over the DBus asynchronously. Callback is used to notify when the remote object is fully created and accessible.

username :

 name of the user

callback :

 GumUserCb to be invoked when user object is fetched

user_data :

 user data

Returns :

 GumUser object. [transfer full]

gum_user_get_by_name_sync ()

GumUser *           gum_user_get_by_name_sync           (const gchar *username);

This method gets the user object attached to username over the DBus synchronously.

username :

 name of the user

Returns :

 GumUser object. [transfer full]

gum_user_get_sync ()

GumUser *           gum_user_get_sync                   (uid_t uid);

This method gets the user object attached to uid over the DBus synchronously.

uid :

 user id for the user

Returns :

 GumUser object. [transfer full]

gum_user_update ()

gboolean            gum_user_update                     (GumUser *self,
                                                         GumUserCb callback,
                                                         gpointer user_data);

This method updates the user over the DBus asynchronously. Callback is used to notify when the user is updated. The properties which can be updated are: secret, realname, office, officephone, homephone and shell.

self :

 GumUser object to be updated; object should have valid "uid" property.

callback :

 GumUserCb to be invoked when user is updated

user_data :

 user data

Returns :

 returns TRUE if the request has been pushed and is waiting for the response, FALSE otherwise. No callback is triggered, in case the function returns FALSE.

gum_user_update_sync ()

gboolean            gum_user_update_sync                (GumUser *self);

This method updates the user over the DBus synchronously. The properties which can be updated are: secret, realname, office, officephone, homephone and shell.

self :

 GumUser object to be updated; object should have valid "uid" property.

Returns :

 returns TRUE if successful, FALSE otherwise.

Property Details

The "gid" property

  "gid"                      guint                 : Read

This property holds a unique group identity for the user as assigned by the underlying framework, which is always be in range [0, MAXUINT].

Default value: 4294967295

The "homedir" property

  "homedir"                  gchar*                : Read / Write

This property holds the location of the home directory of the user. Home directory should not contain any control chars (0x00-0x1F,0x7F), comma (',' 0x2c) or colon (':' 0x3A). For new user, it is recommended to let the underlying framework to set the home directory of the user based on the configuration.

Default value: ""

The "homephone" property

  "homephone"                gchar*                : Read / Write

This property holds the home phone of the user. Home phone should not contain any control chars (0x00-0x1F,0x7F), comma (',' 0x2c) or colon (':' 0x3A).

Default value: ""

The "nickname" property

  "nickname"                 gchar*                : Read / Write

This property holds the nickname of given to the user. Nickname should not contain any control chars (0x00-0x1F,0x7F), comma (',' 0x2c) or colon (':' 0x3A). If no "username" is specified, nickname is hashed to handle non-ascii characters and then set as "username".

Default value: ""

The "office" property

  "office"                   gchar*                : Read / Write

This property holds the location of the office of the user. Office should not contain any control chars (0x00-0x1F,0x7F), comma (',' 0x2c) or colon (':' 0x3A).

Default value: ""

The "officephone" property

  "officephone"              gchar*                : Read / Write

This property holds the office phone of the user. Office phone should not contain any control chars (0x00-0x1F,0x7F), comma (',' 0x2c) or colon (':' 0x3A).

Default value: ""

The "realname" property

  "realname"                 gchar*                : Read / Write

This property holds the realname of given to the user. Realname should not contain any control chars (0x00-0x1F,0x7F), comma (',' 0x2c) or colon (':' 0x3A).

Default value: ""

The "secret" property

  "secret"                   gchar*                : Read / Write

This property holds the secret as chosen by the user. Secret should not contain any control chars (0x00-0x1F,0x7F) or colon (':' 0x3A).

Default value: ""

The "shell" property

  "shell"                    gchar*                : Read / Write

This property holds the shell path of the user. Shell path should not contain any control chars (0x00-0x1F,0x7F), comma (',' 0x2c) or colon (':' 0x3A). For new user, it is recommended to let the underlying framework to set the home directory of the user based on the configuration.

Default value: ""

The "uid" property

  "uid"                      guint                 : Read

This property holds a unique user identity for the user as assigned by ther underlying framework, which is always be in range [0, MAXUINT].

Default value: 4294967295

The "username" property

  "username"                 gchar*                : Read / Write

This property holds the name of given to the user when the user is added. Allowed pattern for username is: "^[A-Za-z_][A-Za-z0-9_.-]*[A-Za-z0-9_.$-]\\?$". Either "username" or "nickname" must be specified when adding a new user.

Default value: ""

The "usertype" property

  "usertype"                 guint                 : Read / Write

This property holds a user type that the object corresponds to. Valid values of user types are as specified in GumUserType. "usertype" must be specified when adding a new user.

Allowed values: <= 65535

Default value: 0

Generated by GTK-Doc V1.18