gumd API Reference Manual: GumGroup

GumGroup

GumGroup — provides interface for managing group's data

Functions

void	(*GumGroupCb) ()
GumGroup *	gum_group_create ()
GumGroup *	gum_group_create_sync ()
GumGroup *	gum_group_get ()
GumGroup *	gum_group_get_sync ()
GumGroup *	gum_group_get_by_name ()
GumGroup *	gum_group_get_by_name_sync ()
gboolean	gum_group_add ()
gboolean	gum_group_add_sync ()
gboolean	gum_group_delete ()
gboolean	gum_group_delete_sync ()
gboolean	gum_group_update ()
gboolean	gum_group_update_sync ()
gboolean	gum_group_add_member ()
gboolean	gum_group_add_member_sync ()
gboolean	gum_group_delete_member ()
gboolean	gum_group_delete_member_sync ()

Properties

guint	gid	Read
gchar *	groupname	Read / Write
guint	grouptype	Read / Write
gboolean	offline	Read / Write / Construct Only
gchar *	secret	Read / Write

Object Hierarchy

    GObject
    ╰── GumGroup

Includes

#include <gum/gum-group.h>

Description

GumGroup provides interface for adding, removing and updating group. Group'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 group object:

 GumGroup *group = NULL;

 group = gum_group_create_sync (FALSE);

 // use the object

 // destroy the object
 g_object_unref (group);

Similarly, new group can be added as:

 GumGroup *group = NULL;
 gboolean rval = FALSE;

 group = gum_group_create_sync (FALSE);

 // set group properties
 g_object_set (G_OBJECT (group), "groupname", "group1", "secret", "123456",
  "grouptype", GUM_GROUPTYPE_USER, NULL);

 // add group
 rval = gum_group_add_sync (user);

 // destroy the object
 g_object_unref (group);

For more details, see command-line utility implementation here:

gum-utils

Functions

GumGroupCb ()

void
(*GumGroupCb) (GumGroup *group,
               const GError *error,
               gpointer user_data);

GumGroupCb defines the callback which is used when group object is created, added, deleted or updated or new members are added to the group.

Parameters

group	GumGroup 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_group_create ()

GumGroup *
gum_group_create (GumGroupCb callback,
                  gpointer user_data);

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

Parameters

callback	GumGroupCb to be invoked when new group object is created
user_data	user data

Returns

GumGroup newly created object.

[transfer full]

gum_group_create_sync ()

GumGroup *
gum_group_create_sync (gboolean offline);

This method creates a new remote group object. In case offline mode is enabled, then the object is created directly without using dbus otherwise the objects gets created over the DBus synchronously.

Parameters

offline

enables or disables the offline mode

Returns

GumGroup newly created object.

[transfer full]

gum_group_get ()

GumGroup *
gum_group_get (gid_t gid,
               GumGroupCb callback,
               gpointer user_data);

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

Parameters

gid	group id for the group
callback	GumGroupCb to be invoked when group object is fetched
user_data	user data

Returns

GumGroup object.

[transfer full]

gum_group_get_sync ()

GumGroup *
gum_group_get_sync (gid_t gid,
                    gboolean offline);

This method gets the group object attached to gid. In case offline mode is enabled, then the object is retrieved directly without using dbus otherwise the objects gets retrieved over the DBus synchronously.

Parameters

gid	group id for the group
offline	enables or disables the offline mode

Returns

GumGroup object.

[transfer full]

gum_group_get_by_name ()

GumGroup *
gum_group_get_by_name (const gchar *groupname,
                       GumGroupCb callback,
                       gpointer user_data);

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

Parameters

groupname	name of the group
callback	GumGroupCb to be invoked when group object is fetched
user_data	user data

Returns

GumGroup object.

[transfer full]

gum_group_get_by_name_sync ()

GumGroup *
gum_group_get_by_name_sync (const gchar *groupname,
                            gboolean offline);

This method gets the group object attached to groupname. In case offline mode is enabled, then the object is retrieved directly without using dbus otherwise the objects gets retrieved over the DBus synchronously.

Parameters

groupname	name of the group
offline	enables or disables the offline mode

Returns

GumGroup object.

[transfer full]

gum_group_add ()

gboolean
gum_group_add (GumGroup *self,
               GumGroupCb callback,
               gpointer user_data);

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

Parameters

self	GumGroup object to be added; object should have valid “groupname” and “grouptype” properties.
callback	GumGroupCb to be invoked when group 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_group_add_sync ()

gboolean
gum_group_add_sync (GumGroup *self);

This method adds the group. In case offline mode is enabled, then the group is added directly without using dbus otherwise the group is added over the DBus synchronously.

Parameters

self

GumGroup object to be added; object should have valid “groupname” and “grouptype” properties.

Returns

returns TRUE if successful, FALSE otherwise.

gum_group_delete ()

gboolean
gum_group_delete (GumGroup *self,
                  GumGroupCb callback,
                  gpointer user_data);

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

Parameters

self	GumGroup object to be deleted; object should have valid “gid” property.
callback	GumGroupCb to be invoked when group 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_group_delete_sync ()

gboolean
gum_group_delete_sync (GumGroup *self);

This method deletes the group. In case offline mode is enabled, then group is deleted directly without using dbus otherwise the group is deleted over DBus synchronously.

Parameters

self

GumGroup object to be deleted; object should have valid “gid” property.

Returns

returns TRUE if successful, FALSE otherwise.

gum_group_update ()

gboolean
gum_group_update (GumGroup *self,
                  GumGroupCb callback,
                  gpointer user_data);

This method updates the group over the DBus asynchronously. Callback is used to notify when the group is updated. The properties which can be updated are: secret.

Parameters

self	GumGroup object to be updated; object should have valid “gid” property.
callback	GumGroupCb to be invoked when group 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_group_update_sync ()

gboolean
gum_group_update_sync (GumGroup *self);

This method updates the group. In case offline mode is enabled, then group is updated directly without using dbus otherwise the group is updated over DBus synchronously. The properties which can be updated are: secret.

Parameters

self

GumGroup object to be updated; object should have valid “gid” property.

Returns

returns TRUE if successful, FALSE otherwise.

gum_group_add_member ()

gboolean
gum_group_add_member (GumGroup *self,
                      uid_t uid,
                      gboolean add_as_admin,
                      GumGroupCb callback,
                      gpointer user_data);

This method adds new member to the group over the DBus asynchronously. Callback is used to notify when the member is added.

Parameters

self	GumGroup object where new member is to be added; object should have valid “gid” property.
uid	user id of the member to be added to the group
add_as_admin	user will be added with admin privileges for the group if set to TRUE
callback	GumGroupCb to be invoked when member 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_group_add_member_sync ()

gboolean
gum_group_add_member_sync (GumGroup *self,
                           uid_t uid,
                           gboolean add_as_admin);

This method adds new member to the group. In case offline mode is enabled, then group member is added directly without using dbus otherwise member is added over DBus synchronously.

Parameters

self	GumGroup object where new member is to be added; object should have valid “gid” property.
uid	user id of the member to be added to the group
add_as_admin	user will be added with admin privileges for the group if set to TRUE

Returns

returns TRUE if successful, FALSE otherwise.

gum_group_delete_member ()

gboolean
gum_group_delete_member (GumGroup *self,
                         uid_t uid,
                         GumGroupCb callback,
                         gpointer user_data);

This method deletes new member from the group over the DBus asynchronously. Callback is used to notify when the member is deleted.

Parameters

self	GumGroup object where member is to be deleted from; object should have valid “gid” property.
uid	user id of the member to be deleted from the group
callback	GumGroupCb to be invoked when member 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_group_delete_member_sync ()

gboolean
gum_group_delete_member_sync (GumGroup *self,
                              uid_t uid);

This method deletes new member from the group. In case offline mode is enabled, then group member is deleted directly without using dbus otherwise member is deleted over DBus synchronously.

Parameters

self	GumGroup object where member is to be deleted from; object should have valid “gid” property.
uid	user id of the member to be deleted from the group

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 group as assigned by the underlying framework, which is always be in range [0, MAXUINT].

Flags: Read

Default value: 4294967295

The `“groupname”` property

  “groupname”                gchar *

This property holds the name of given to the group when the group is added. Allowed pattern for groupname is: "^A-Za-z_*[A-Za-z0-9_.$-]\?$".

Flags: Read / Write

Default value: ""

The `“grouptype”` property

  “grouptype”                guint

This property holds a group type that the object corresponds to. Valid values of group types are as specified in GumGroupType. “grouptype” must be specified when adding a new group.

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

The `“offline”` property

  “offline”                  gboolean

Operational mode for the Group object.

Flags: Read / Write / Construct Only

Default value: FALSE

The `“secret”` property

  “secret”                   gchar *

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

Flags: Read / Write

Default value: ""

GumGroup

Functions

Properties

Object Hierarchy

Includes

Description

Functions

GumGroupCb ()

Parameters

gum_group_create ()

Parameters

Returns

gum_group_create_sync ()

Parameters

Returns

gum_group_get ()

Parameters

Returns

gum_group_get_sync ()

Parameters

Returns

gum_group_get_by_name ()

Parameters

Returns

gum_group_get_by_name_sync ()

Parameters

Returns

gum_group_add ()

Parameters

Returns

gum_group_add_sync ()

Parameters

Returns

gum_group_delete ()

Parameters

Returns

gum_group_delete_sync ()

Parameters

Returns

gum_group_update ()

Parameters

Returns

gum_group_update_sync ()

Parameters

Returns

gum_group_add_member ()

Parameters

Returns

gum_group_add_member_sync ()

Parameters

Returns

gum_group_delete_member ()

Parameters

Returns

gum_group_delete_member_sync ()

Parameters

Returns

Types and Values

Property Details

The “gid” property

The “groupname” property

The “grouptype” property

The “offline” property

The “secret” property

The `“gid”` property

The `“groupname”` property

The `“grouptype”` property

The `“offline”` property

The `“secret”` property