gumd API Reference Manual: GumUser

GumUser

GumUser — provides interface for managing user's account

Functions

void	(*GumUserCb) ()
GumUser *	gum_user_create ()
GumUser *	gum_user_create_sync ()
GumUser *	gum_user_get ()
GumUser *	gum_user_get_sync ()
GumUser *	gum_user_get_by_name ()
GumUser *	gum_user_get_by_name_sync ()
gboolean	gum_user_add ()
gboolean	gum_user_add_sync ()
gboolean	gum_user_delete ()
gboolean	gum_user_delete_sync ()
gboolean	gum_user_update ()
gboolean	gum_user_update_sync ()

Properties

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

Object Hierarchy

    GObject
    ╰── GumUser

Includes

#include <gum/gum-user.h>

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

Functions

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.

Parameters

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

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.

Parameters

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_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.

Parameters

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_sync ()

GumUser *
gum_user_get_sync (uid_t uid);

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

Parameters

uid

user id for the user

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.

Parameters

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.

Parameters

username

name of the user

Returns

GumUser object.

[transfer full]

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.

Parameters

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.

Parameters

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_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.

Parameters

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.

Parameters

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_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.

Parameters

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.

Parameters

self

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

Returns

returns TRUE if successful, FALSE otherwise.

Types and Values

Property Details

The `“gid”` property

  “gid”                      guint

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

Flags: Read

Default value: 4294967295

The `“homedir”` property

  “homedir”                  gchar *

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.

Flags: Read / Write

Default value: ""

The `“homephone”` property

  “homephone”                gchar *

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).

Flags: Read / Write

Default value: ""

The `“nickname”` property

  “nickname”                 gchar *

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”.

Flags: Read / Write

Default value: ""

The `“office”` property

  “office”                   gchar *

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).

Flags: Read / Write

Default value: ""

The `“officephone”` property

  “officephone”              gchar *

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).

Flags: Read / Write

Default value: ""

The `“realname”` property

  “realname”                 gchar *

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).

Flags: Read / Write

Default value: ""

The `“secret”` property

  “secret”                   gchar *

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

Flags: Read / Write

Default value: ""

The `“shell”` property

  “shell”                    gchar *

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.

Flags: Read / Write

Default value: ""

The `“uid”` property

  “uid”                      guint

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

Flags: Read

Default value: 4294967295

The `“username”` property

  “username”                 gchar *

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_.$-]\?$". Either “username” or “nickname” must be specified when adding a new user.

Flags: Read / Write

Default value: ""

The `“usertype”` property

  “usertype”                 guint

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.

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

GumUser

Functions

Properties

Object Hierarchy

Includes

Description

Functions

GumUserCb ()

Parameters

gum_user_create ()

Parameters

Returns

gum_user_create_sync ()

Returns

gum_user_get ()

Parameters

Returns

gum_user_get_sync ()

Parameters

Returns

gum_user_get_by_name ()

Parameters

Returns

gum_user_get_by_name_sync ()

Parameters

Returns

gum_user_add ()

Parameters

Returns

gum_user_add_sync ()

Parameters

Returns

gum_user_delete ()

Parameters

Returns

gum_user_delete_sync ()

Parameters

Returns

gum_user_update ()

Parameters

Returns

gum_user_update_sync ()

Parameters

Returns

Types and Values

Property Details

The “gid” property

The “homedir” property

The “homephone” property

The “nickname” property

The “office” property

The “officephone” property

The “realname” property

The “secret” property

The “shell” property

The “uid” property

The “username” property

The “usertype” property

The `“gid”` property

The `“homedir”` property

The `“homephone”` property

The `“nickname”` property

The `“office”` property

The `“officephone”` property

The `“realname”` property

The `“secret”` property

The `“shell”` property

The `“uid”` property

The `“username”` property

The `“usertype”` property