#include "gum-group-service.h"
#include "gum-internals.h"
+/**
+ * SECTION:gum-group
+ * @short_description: provides interface for managing group's data
+ * @include: common/gum-group.h
+ *
+ * #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:
+ *
+ * |[
+ * GMainLoop *main_loop = NULL;
+ * GumGroup *group = NULL;
+ *
+ * main_loop = g_main_loop_new (NULL, FALSE)
+ * group = gum_group_create (_on_group_created, NULL);
+ *
+ * // wait for _on_group_created callback and use the object when callback is
+ * // triggered
+ * g_main_loop_run (main_loop);
+ *
+ * // destroy the object
+ * g_object_unref (group);
+ * ]|
+ *
+ * Similarly, new group can be added as:
+ * |[
+ * GMainLoop *main_loop = NULL;
+ * GumGroup *group = NULL;
+ * gboolean rval = FALSE;
+ *
+ * main_loop = g_main_loop_new (NULL, FALSE)
+ * group = gum_group_create (_on_group_created, NULL);
+ *
+ * // wait for _on_group_created callback and use the object when callback is
+ * // triggered
+ * g_main_loop_run (main_loop);
+ *
+ * // set group properties
+ * g_object_set (G_OBJECT (group), "groupname", "group1", "secret", "123456",
+ * "grouptype", GUM_GROUPTYPE_USER, NULL);
+ *
+ * // add group
+ * rval = gum_group_add (user, _on_group_added, NULL);
+ *
+ * // wait for _on_group_added callback
+ * g_main_loop_run (main_loop);
+ *
+ * // destroy the object
+ * g_object_unref (group);
+ * ]|
+ *
+ * For more details, see example implementation here:
+ *<ulink url="https://github.com/01org/gumd/blob/master/examples/gum-example.c">
+ * gum-example</ulink>
+ */
+
+/**
+ * GumGroupCb:
+ * @group: (transfer none): #GumGroup object which is used in the request
+ * @error: (transfer none): #GError object. In case of error, error will be
+ * non-NULL
+ * @user_data: user data passed onto the request
+ *
+ * #GumGroupCb defines the callback which is used when group object is created,
+ * added, deleted or updated or new members are added to the group.
+ */
+
typedef struct {
GumGroupCb callback;
gpointer user_data;
object_class->dispose = _dispose;
object_class->finalize = _finalize;
+ /**
+ * GumGroup:grouptype:
+ *
+ * This property holds a group type that the object corresponds to. Valid
+ * values of group types are; 1 (system), 2 (user).
+ * #GumGroup:grouptype must be specified when adding a new group.
+ */
properties[PROP_GROUPTYPE] = g_param_spec_uint ("grouptype",
"GroupType",
"Type of the group",
G_PARAM_READWRITE |
G_PARAM_STATIC_STRINGS);
+ /**
+ * GumGroup:gid:
+ *
+ * This property holds a unique group identity for the group as assigned by
+ * the underlying framework, which is always be in range [0, MAXUINT].
+ */
properties[PROP_GID] = g_param_spec_uint ("gid",
"Gid",
"Unique identifier of the group of the group",
G_PARAM_READABLE |
G_PARAM_STATIC_STRINGS);
+ /**
+ * GumGroup:groupname:
+ *
+ * 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_.-]*[A-Za-z0-9_.$-]\\?$".
+ */
properties[PROP_GROUPNAME] = g_param_spec_string ("groupname",
"Groupname",
"System name of the group",
G_PARAM_READWRITE |
G_PARAM_STATIC_STRINGS);
+ /**
+ * GumGroup:secret:
+ *
+ * This property holds the secret as chosen. Secret should not
+ * contain any control chars (0x00-0x1F,0x7F) or colon (':' 0x3A).
+ */
properties[PROP_SECRET] = g_param_spec_string ("secret",
"Secret",
"Group secret",
g_clear_error (&error);
}
+/**
+ * gum_group_create:
+ * @callback: #GumGroupCb to be invoked when new group object is created
+ * @user_data: 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.
+ *
+ * Returns: (transfer full): #GumGroup newly created object
+ */
GumGroup *
gum_group_create (
GumGroupCb callback,
return group;
}
+/**
+ * gum_group_get:
+ * @gid: group id for the group
+ * @callback: #GumGroupCb to be invoked when group object is fetched
+ * @user_data: 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.
+ *
+ * Returns: (transfer full): #GumGroup object
+ */
GumGroup *
gum_group_get (
gid_t gid,
return group;
}
+/**
+ * gum_group_get_by_name:
+ * @groupname: name of the group
+ * @callback: #GumGroupCb to be invoked when group object is fetched
+ * @user_data: 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.
+ *
+ * Returns: (transfer full): #GumGroup object
+ */
GumGroup *
gum_group_get_by_name (
const gchar *groupname,
return group;
}
+/**
+ * gum_group_add:
+ * @self: #GumGroup object to be added; object should have valid
+ * #GumGroup:groupname and #GumGroup:grouptype properties.
+ * @callback: #GumGroupCb to be invoked when group is added
+ * @user_data: user data
+ *
+ * This method adds the group over the DBus asynchronously. Callback is used to
+ * notify when the group is added.
+ *
+ * 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.
+ */
gboolean
gum_group_add (
GumGroup *self,
return TRUE;
}
+/**
+ * gum_group_delete:
+ * @self: #GumGroup object to be deleted; object should have valid
+ * #GumGroup:gid property.
+ * @callback: #GumGroupCb to be invoked when group is deleted
+ * @user_data: user data
+ *
+ * This method deletes the group over the DBus asynchronously. Callback is used
+ * to notify when the group is deleted.
+ *
+ * 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.
+ */
gboolean
gum_group_delete (
GumGroup *self,
return TRUE;
}
+/**
+ * gum_group_update:
+ * @self: #GumGroup object to be updated; object should have valid
+ * #GumGroup:gid property.
+ * @callback: #GumGroupCb to be invoked when group is updated
+ * @user_data: 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.
+ *
+ * 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.
+ */
gboolean
gum_group_update (
GumGroup *self,
return TRUE;
}
+/**
+ * gum_group_add_member:
+ * @self: #GumGroup object where new member is to be added; object should have
+ * valid #GumGroup: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
+ *
+ * This method adds new member to the group over the DBus asynchronously.
+ * Callback is used to notify when the member is added.
+ *
+ * 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.
+ */
gboolean
gum_group_add_member (
GumGroup *self,
return TRUE;
}
+/**
+ * gum_group_delete_member:
+ * @self: #GumGroup object where member is to be deleted from; object should
+ * have valid #GumGroup: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
+ *
+ * This method deletes new member from the group over the DBus asynchronously.
+ * Callback is used to notify when the member is deleted.
+ *
+ * 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.
+ */
gboolean
gum_group_delete_member (
GumGroup *self,
* #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 use management daemon.
+ * communication with the user management daemon.
*
* Following code snippet demonstrates how to create a new remote user object:
*
/**
* GumUserCb:
- *
* @user: (transfer none): #GumUser object which is used in the request
* @error: (transfer none): #GError object. In case of error, error will be
* non-NULL
* @user_data: user data passed onto the request
*
- * #GumUserCb specifies the callback signature when user object is created,
+ * #GumUserCb defines the callback which is used when user object is created,
* added, deleted or updated.
*/
/**
* GumUser:gid:
*
- * This property holds a unique groupd identity for the user as assigned by
+ * This property holds a unique group identity for the user as assigned by
* the underlying framework, which is always be in range [0, MAXUINT].
*/
properties[PROP_GID] = g_param_spec_uint ("gid",
/**
* gum_user_add:
- * @self: #GumUser object to be added
+ * @self: #GumUser object to be added; object should have either valid
+ * #GumUser:username or #GumUser:nickname in addition to valid
+ * #GumUser:usertype.
* @callback: #GumUserCb to be invoked when user is added
* @user_data: user data
*
* This method adds the user over the DBus asynchronously. Callback is used to
* notify when the user is added.
*
- * Returns: returns TRUE if the request to DBus is successful, FALSE otherwise.
- * When FALSE, no callback is triggered.
+ * 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.
*/
gboolean
gum_user_add (
/**
* gum_user_delete:
- * @self: #GumUser object to be deleted
+ * @self: #GumUser object to be deleted; object should have valid #GumUser: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
*
* This method deletes the user over the DBus asynchronously. Callback is used
* to notify when the user is deleted.
*
- * Returns: returns TRUE if the request to DBus is successful, FALSE otherwise.
- * When FALSE, no callback is triggered.
+ * 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.
*/
gboolean
gum_user_delete (
/**
* gum_user_update:
- * @self: #GumUser object to be updated
+ * @self: #GumUser object to be updated; object should have valid #GumUser:uid
+ * property.
* @callback: #GumUserCb to be invoked when user is updated
* @user_data: 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.
+ * to notify when the user is updated. The properties which can be updated
+ * are: secret, realname, office, officephone, homephone and shell.
*
- * Returns: returns TRUE if the request to DBus is successful, FALSE otherwise.
- * When FALSE, no callback is triggered.
+ * 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.
*/
gboolean
gum_user_update (
projects / platform / upstream / gumd.git / commitdiff