From: David Zeuthen Date: Mon, 8 Jun 2009 14:53:36 +0000 (-0400) Subject: Add some more API docs X-Git-Tag: 0.92~10 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=b0e8a91269db5270f43d8b213dc3298b12c22a4f;p=platform%2Fupstream%2Fpolkit.git Add some more API docs --- diff --git a/docs/polkit/polkit-1-sections.txt b/docs/polkit/polkit-1-sections.txt index 46eedbb..1516bbf 100644 --- a/docs/polkit/polkit-1-sections.txt +++ b/docs/polkit/polkit-1-sections.txt @@ -17,6 +17,37 @@ POLKIT_UNIX_USER_GET_CLASS
+polkitauthority +PolkitAuthority +PolkitCheckAuthorizationFlags +polkit_authority_get +polkit_authority_check_authorization +polkit_authority_check_authorization_finish +polkit_authority_enumerate_actions +polkit_authority_enumerate_actions_finish +polkit_authority_register_authentication_agent +polkit_authority_register_authentication_agent_finish +polkit_authority_unregister_authentication_agent +polkit_authority_unregister_authentication_agent_finish +polkit_authority_authentication_agent_response +polkit_authority_authentication_agent_response_finish +polkit_authority_check_authorization_sync +polkit_authority_enumerate_actions_sync +polkit_authority_register_authentication_agent_sync +polkit_authority_unregister_authentication_agent_sync +polkit_authority_authentication_agent_response_sync + +PolkitAuthorityClass +POLKIT_AUTHORITY +POLKIT_IS_AUTHORITY +POLKIT_TYPE_AUTHORITY +polkit_authority_get_type +POLKIT_AUTHORITY_CLASS +POLKIT_IS_AUTHORITY_CLASS +POLKIT_AUTHORITY_GET_CLASS +
+ +
polkitauthoritymanager PolkitAuthorityManager polkit_authority_manager_get @@ -47,37 +78,6 @@ POLKIT_AUTHORITY_MANAGER_GET_CLASS
-polkitauthority -PolkitAuthority -PolkitCheckAuthorizationFlags -polkit_authority_get -polkit_authority_enumerate_actions_sync -polkit_authority_check_authorization_sync -polkit_authority_register_authentication_agent_sync -polkit_authority_unregister_authentication_agent_sync -polkit_authority_authentication_agent_response_sync -polkit_authority_enumerate_actions -polkit_authority_enumerate_actions_finish -polkit_authority_check_authorization -polkit_authority_check_authorization_finish -polkit_authority_register_authentication_agent -polkit_authority_register_authentication_agent_finish -polkit_authority_unregister_authentication_agent -polkit_authority_unregister_authentication_agent_finish -polkit_authority_authentication_agent_response -polkit_authority_authentication_agent_response_finish - -PolkitAuthorityClass -POLKIT_AUTHORITY -POLKIT_IS_AUTHORITY -POLKIT_TYPE_AUTHORITY -polkit_authority_get_type -POLKIT_AUTHORITY_CLASS -POLKIT_IS_AUTHORITY_CLASS -POLKIT_AUTHORITY_GET_CLASS -
- -
polkitauthorizationresult PolkitAuthorizationResult polkit_authorization_result_new @@ -262,10 +262,10 @@ polkit_implicit_authorization_get_type
polkiterror POLKIT_ERROR -POLKIT_TYPE_ERROR PolkitError polkit_error_quark +POLKIT_TYPE_ERROR polkit_error_get_type
diff --git a/src/polkit/polkitactiondescription.c b/src/polkit/polkitactiondescription.c index f022114..f36b68d 100644 --- a/src/polkit/polkitactiondescription.c +++ b/src/polkit/polkitactiondescription.c @@ -35,9 +35,14 @@ * @title: PolkitActionDescription * @short_description: Actions * - * Encapsulates an action. + * Object used to encapsulate a registered action. */ +/** + * PolkitActionDescription: + * + * The #PolkitActionDescription struct should not be accessed directly. + */ struct _PolkitActionDescription { GObject parent_instance; @@ -99,48 +104,117 @@ polkit_action_description_get_real (PolkitActionDescription *action_description) return g_object_ref (action_description->real); } +/** + * polkit_action_description_get_action_id: + * @action_description: A #PolkitActionDescription. + * + * Gets the action id for @action_description. + * + * Returns: A string owned by @action_description. Do not free. + */ const gchar * polkit_action_description_get_action_id (PolkitActionDescription *action_description) { return _polkit_action_description_get_action_id (action_description->real); } +/** + * polkit_action_description_get_description: + * @action_description: A #PolkitActionDescription. + * + * Gets the description used for @action_description. + * + * Returns: A string owned by @action_description. Do not free. + */ const gchar * polkit_action_description_get_description (PolkitActionDescription *action_description) { return _polkit_action_description_get_description (action_description->real); } +/** + * polkit_action_description_get_message: + * @action_description: A #PolkitActionDescription. + * + * Gets the message used for @action_description. + * + * Returns: A string owned by @action_description. Do not free. + */ const gchar * polkit_action_description_get_message (PolkitActionDescription *action_description) { return _polkit_action_description_get_message (action_description->real); } +/** + * polkit_action_description_get_vendor_name: + * @action_description: A #PolkitActionDescription. + * + * Gets the vendor name for @action_description, if any. + * + * Returns: %NULL if there is no vendor, otherwise a string owned by + * @action_description. Do not free. + */ const gchar * polkit_action_description_get_vendor_name (PolkitActionDescription *action_description) { return _polkit_action_description_get_vendor_name (action_description->real); } +/** + * polkit_action_description_get_vendor_url: + * @action_description: A #PolkitActionDescription. + * + * Gets the vendor URL for @action_description, if any. + * + * Returns: %NULL if there is no vendor URL, otherwise a string owned + * by @action_description. Do not free. + */ const gchar * polkit_action_description_get_vendor_url (PolkitActionDescription *action_description) { return _polkit_action_description_get_vendor_url (action_description->real); } +/** + * polkit_action_description_get_implicit_any: + * @action_description: A #PolkitActionDescription. + * + * Gets the implicit authorization for @action_description used for + * any subject. + * + * Returns: A value from the #PolkitImplicitAuthorization enumeration. + */ PolkitImplicitAuthorization polkit_action_description_get_implicit_any (PolkitActionDescription *action_description) { return _polkit_action_description_get_implicit_any (action_description->real); } +/** + * polkit_action_description_get_implicit_inactive: + * @action_description: A #PolkitActionDescription. + * + * Gets the implicit authorization for @action_description used for + * subjects in inactive sessions on a local console. + * + * Returns: A value from the #PolkitImplicitAuthorization enumeration. + */ PolkitImplicitAuthorization polkit_action_description_get_implicit_inactive (PolkitActionDescription *action_description) { return _polkit_action_description_get_implicit_inactive (action_description->real); } +/** + * polkit_action_description_get_implicit_active: + * @action_description: A #PolkitActionDescription. + * + * Gets the implicit authorization for @action_description used for + * subjects in active sessions on a local console. + * + * Returns: A value from the #PolkitImplicitAuthorization enumeration. + */ PolkitImplicitAuthorization polkit_action_description_get_implicit_active (PolkitActionDescription *action_description) { @@ -148,12 +222,31 @@ polkit_action_description_get_implicit_active (PolkitActionDescription *action_d } +/** + * polkit_action_description_get_icon_name: + * @action_description: A #PolkitActionDescription. + * + * Gets the icon name for @action_description, if any. + * + * Returns: %NULL if there is no icon for @action, otherwise the icon + * name owned by @action_description. Do not free. + */ const gchar * polkit_action_description_get_icon_name (PolkitActionDescription *action_description) { return _polkit_action_description_get_icon_name (action_description->real); } +/** + * polkit_action_description_get_annotation: + * @action_description: A #PolkitActionDescription. + * @key: An annotation key. + * + * Get the value of the annotation with @key. + * + * Returns: %NULL if there is no annoation with @key, otherwise the + * annotation value owned by @action_description. Do not free. + */ const gchar * polkit_action_description_get_annotation (PolkitActionDescription *action_description, const gchar *key) @@ -179,6 +272,14 @@ collect_keys (EggDBusHashMap *hash_map, } +/** + * polkit_action_description_get_annotation_keys: + * @action_description: A #PolkitActionDescription. + * + * Gets the keys of annotations defined in @action_description. + * + * Returns: The annotation keys owned by @action_description. Do not free. + */ const gchar * const * polkit_action_description_get_annotation_keys (PolkitActionDescription *action_description) { @@ -201,4 +302,3 @@ polkit_action_description_get_annotation_keys (PolkitActionDescription *action_d out: return (const gchar * const *) action_description->annotation_keys; } - diff --git a/src/polkit/polkitauthority.c b/src/polkit/polkitauthority.c index 0ca8fd9..4bb7ecd 100644 --- a/src/polkit/polkitauthority.c +++ b/src/polkit/polkitauthority.c @@ -44,7 +44,8 @@ * User sessions can register an authentication agent with the * authority. This is used for requests from untrusted clients where * system policy requires that the user needs to acknowledge (through - * proving he is the user or the administrator) a given action. + * proving he is the user or the administrator) a given action. See + * #PolkitAgentListener and #PolkitAgentSession for details. */ /** diff --git a/src/polkit/polkitauthorizationresult.c b/src/polkit/polkitauthorizationresult.c index e9961c0..6786a5a 100644 --- a/src/polkit/polkitauthorizationresult.c +++ b/src/polkit/polkitauthorizationresult.c @@ -35,6 +35,11 @@ * This class represents the result you get when checking for an authorization. */ +/** + * PolkitAuthorizationResult: + * + * The #PolkitAuthorizationResult struct should not be accessed directly. + */ struct _PolkitAuthorizationResult { GObject parent_instance; @@ -101,14 +106,16 @@ polkit_authorization_result_get_real (PolkitAuthorizationResult *authorization_ /** * polkit_authorization_result_new: - * @is_authorized: - * @is_challenge: - * @details: + * @is_authorized: Whether the subject is authorized. + * @is_challenge: Whether the subject is authorized if more + * information is provided. Must be %FALSE unless @is_authorized is + * %TRUE. + * @details: Must be %NULL unless @is_authorized is %TRUE * + * Creates a new #PolkitAuthorizationResult object. * - * - * Returns: - **/ + * Returns: A #PolkitAuthorizationResult object. Free with g_object_unref(). + */ PolkitAuthorizationResult * polkit_authorization_result_new (gboolean is_authorized, gboolean is_challenge, @@ -148,12 +155,12 @@ polkit_authorization_result_new (gboolean is_authorized, /** * polkit_authorization_result_get_is_authorized: - * @result: - * + * @result: A #PolkitAuthorizationResult. * + * Gets whether the subject is authorized. * - * Returns: - **/ + * Returns: Whether the subject is authorized. + */ gboolean polkit_authorization_result_get_is_authorized (PolkitAuthorizationResult *result) { @@ -162,12 +169,12 @@ polkit_authorization_result_get_is_authorized (PolkitAuthorizationResult *result /** * polkit_authorization_result_get_is_challenge: - * @result: - * + * @result: A #PolkitAuthorizationResult. * + * Gets whether the subject is authorized if more information is provided. * - * Returns: - **/ + * Returns: Whether the subject is authorized if more information is provided. + */ gboolean polkit_authorization_result_get_is_challenge (PolkitAuthorizationResult *result) { @@ -176,12 +183,13 @@ polkit_authorization_result_get_is_challenge (PolkitAuthorizationResult *result) /** * polkit_authorization_result_get_details: - * @result: + * @result: A #PolkitAuthorizationResult. * + * Gets the details about the result. * - * - * Returns: - **/ + * Returns: A #PolkitDetails object. This object is owned by @result + * and should not be freed by the caller. + */ PolkitDetails * polkit_authorization_result_get_details (PolkitAuthorizationResult *result) { diff --git a/src/polkit/polkitdetails.c b/src/polkit/polkitdetails.c index bef0704..2ef9e78 100644 --- a/src/polkit/polkitdetails.c +++ b/src/polkit/polkitdetails.c @@ -32,11 +32,17 @@ /** * SECTION:polkitdetails * @title: PolkitDetails - * @short_description: Details + * @short_description: Object used for passing details + * @stability: Stable * * An object used for passing details around. */ +/** + * PolkitDetails: + * + * The #PolkitDetails struct should not be accessed directly. + */ struct _PolkitDetails { GObject parent_instance; @@ -78,6 +84,13 @@ polkit_details_class_init (PolkitDetailsClass *klass) gobject_class->finalize = polkit_details_finalize; } +/** + * polkit_details_new: + * + * Creates a new #PolkitDetails object. + * + * Returns: A #PolkitDetails object. Free with g_object_unref(). + */ PolkitDetails * polkit_details_new (void) { @@ -88,6 +101,7 @@ polkit_details_new (void) return details; } +/* private */ PolkitDetails * polkit_details_new_for_hash (GHashTable *hash) { @@ -100,12 +114,22 @@ polkit_details_new_for_hash (GHashTable *hash) return details; } +/* private */ GHashTable * polkit_details_get_hash (PolkitDetails *details) { return details->hash; } +/** + * polkit_details_lookup: + * @details: A #PolkitDetails. + * @key: A key. + * + * Gets the value for @key on @details. + * + * Returns: %NULL if there is no value for @key, otherwise a string owned by @details. + */ const gchar * polkit_details_lookup (PolkitDetails *details, const gchar *key) @@ -116,6 +140,14 @@ polkit_details_lookup (PolkitDetails *details, return g_hash_table_lookup (details->hash, key); } +/** + * polkit_details_insert: + * @details: A #PolkitDetails. + * @key: A key. + * @value: A value. + * + * Inserts a copy of @key and @value on @details. + */ void polkit_details_insert (PolkitDetails *details, const gchar *key, @@ -129,6 +161,14 @@ polkit_details_insert (PolkitDetails *details, g_hash_table_insert (details->hash, g_strdup (key), g_strdup (value)); } +/** + * polkit_details_get_keys: + * @details: A #PolkitDetails. + * + * Gets a list of all keys on @details. + * + * Returns: An array of strings that should be freed with g_strfreev(). + */ gchar ** polkit_details_get_keys (PolkitDetails *details) { diff --git a/src/polkit/polkitidentity.c b/src/polkit/polkitidentity.c index f1eb852..08fd6ac 100644 --- a/src/polkit/polkitidentity.c +++ b/src/polkit/polkitidentity.c @@ -34,9 +34,10 @@ /** * SECTION:polkitidentity * @title: PolkitIdentity - * @short_description: Identities + * @short_description: Type for representing identities * - * Identities. + * #PolkitIdentity is an abstract type for representing one or more + * identities. */ static void @@ -73,12 +74,31 @@ polkit_identity_get_type (void) return iface_type; } +/** + * polkit_identity_hash: + * @identity: A #PolkitIdentity. + * + * Gets a hash code for @identity that can be used with e.g. g_hash_table_new(). + * + * Returns: A hash code. + */ guint polkit_identity_hash (PolkitIdentity *identity) { return POLKIT_IDENTITY_GET_IFACE (identity)->hash (identity); } +/** + * polkit_identity_equal: + * @a: A #PolkitIdentity. + * @b: A #PolkitIdentity. + * + * Checks if @a and @b are equal, ie. represent the same identity. + * + * This function can be used in e.g. g_hash_table_new(). + * + * Returns: %TRUE if @a and @b are equal, %FALSE otherwise. + */ gboolean polkit_identity_equal (PolkitIdentity *a, PolkitIdentity *b) @@ -89,12 +109,32 @@ polkit_identity_equal (PolkitIdentity *a, return POLKIT_IDENTITY_GET_IFACE (a)->equal (a, b); } +/** + * polkit_identity_to_string: + * @identity: A #PolkitIdentity. + * + * Serializes @identity to a string that can be used in + * polkit_identity_from_string(). + * + * Returns: A string representing @identity. Free with g_free(). + */ gchar * polkit_identity_to_string (PolkitIdentity *identity) { return POLKIT_IDENTITY_GET_IFACE (identity)->to_string (identity); } +/** + * polkit_identity_from_string: + * @str: A string obtained from polkit_identity_to_string(). + * @error: Return location for error. + * + * Creates an object from @str that implements the #PolkitIdentity + * interface. + * + * Returns: A #PolkitIdentity or %NULL if @error is set. Free with + * g_object_unref(). + */ PolkitIdentity * polkit_identity_from_string (const gchar *str, GError **error) diff --git a/src/polkit/polkitidentity.h b/src/polkit/polkitidentity.h index 7d955e6..da908a2 100644 --- a/src/polkit/polkitidentity.h +++ b/src/polkit/polkitidentity.h @@ -38,10 +38,25 @@ G_BEGIN_DECLS #define POLKIT_IDENTITY_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE((o), POLKIT_TYPE_IDENTITY, PolkitIdentityIface)) #if 0 +/** + * PolkitIdentity: + * + * Generic type for all objects that can be used as identities. + */ typedef struct _PolkitIdentity PolkitIdentity; /* Dummy typedef */ #endif typedef struct _PolkitIdentityIface PolkitIdentityIface; +/** + * PolkitIdentityIface: + * @parent_iface: The parent interface. + * @hash: Gets a hash value for a #PolkitIdentity. + * @equal: Checks if two #PolkitIdentitys are equal. + * @to_string: Serializes a #PolkitIdentity to a string that can be + * used in polkit_identity_from_string(). + * + * An interface for identities. + */ struct _PolkitIdentityIface { GTypeInterface parent_iface; diff --git a/src/polkit/polkitsubject.c b/src/polkit/polkitsubject.c index ba097f4..43be6b9 100644 --- a/src/polkit/polkitsubject.c +++ b/src/polkit/polkitsubject.c @@ -35,9 +35,10 @@ /** * SECTION:polkitsubject * @title: PolkitSubject - * @short_description: Subjects + * @short_description: Type for representing subjects * - * Subjects. + * #PolkitSubject is an abstract type for representing one or more + * processes. */ static void @@ -74,12 +75,31 @@ polkit_subject_get_type (void) return iface_type; } +/** + * polkit_subject_hash: + * @subject: A #PolkitSubject. + * + * Gets a hash code for @subject that can be used with e.g. g_hash_table_new(). + * + * Returns: A hash code. + */ guint polkit_subject_hash (PolkitSubject *subject) { return POLKIT_SUBJECT_GET_IFACE (subject)->hash (subject); } +/** + * polkit_subject_equal: + * @a: A #PolkitSubject. + * @b: A #PolkitSubject. + * + * Checks if @a and @b are equal, ie. represent the same subject. + * + * This function can be used in e.g. g_hash_table_new(). + * + * Returns: %TRUE if @a and @b are equal, %FALSE otherwise. + */ gboolean polkit_subject_equal (PolkitSubject *a, PolkitSubject *b) @@ -90,12 +110,32 @@ polkit_subject_equal (PolkitSubject *a, return POLKIT_SUBJECT_GET_IFACE (a)->equal (a, b); } +/** + * polkit_subject_to_string: + * @subject: A #PolkitSubject. + * + * Serializes @subject to a string that can be used in + * polkit_subject_from_string(). + * + * Returns: A string representing @subject. Free with g_free(). + */ gchar * polkit_subject_to_string (PolkitSubject *subject) { return POLKIT_SUBJECT_GET_IFACE (subject)->to_string (subject); } +/** + * polkit_subject_from_string: + * @str: A string obtained from polkit_subject_to_string(). + * @error: Return location for error. + * + * Creates an object from @str that implements the #PolkitSubject + * interface. + * + * Returns: A #PolkitSubject or %NULL if @error is set. Free with + * g_object_unref(). + */ PolkitSubject * polkit_subject_from_string (const gchar *str, GError **error) @@ -249,4 +289,3 @@ polkit_subject_get_real (PolkitSubject *subject) return real; } - diff --git a/src/polkit/polkitsubject.h b/src/polkit/polkitsubject.h index 0ef8812..6eb8fef 100644 --- a/src/polkit/polkitsubject.h +++ b/src/polkit/polkitsubject.h @@ -38,10 +38,25 @@ G_BEGIN_DECLS #define POLKIT_SUBJECT_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE((o), POLKIT_TYPE_SUBJECT, PolkitSubjectIface)) #if 0 +/** + * PolkitSubject: + * + * Generic type for all objects that can be used as subjects. + */ typedef struct _PolkitSubject PolkitSubject; /* Dummy typedef */ #endif typedef struct _PolkitSubjectIface PolkitSubjectIface; +/** + * PolkitSubjectIface: + * @parent_iface: The parent interface. + * @hash: Gets a hash value for a #PolkitSubject. + * @equal: Checks if two #PolkitSubjects are equal. + * @to_string: Serializes a #PolkitSubject to a string that can be + * used in polkit_subject_from_string(). + * + * An interface for subjects. + */ struct _PolkitSubjectIface { GTypeInterface parent_iface; diff --git a/src/polkit/polkitsystembusname.c b/src/polkit/polkitsystembusname.c index bd0c13d..44b71e5 100644 --- a/src/polkit/polkitsystembusname.c +++ b/src/polkit/polkitsystembusname.c @@ -31,11 +31,16 @@ /** * SECTION:polkitsystembusname * @title: PolkitSystemBusName - * @short_description: Unique system bus name + * @short_description: Unique system bus names * - * Encapsulates a process with a unique name on the system bus. + * An object that represents a process owning a unique name on the system bus. */ +/** + * PolkitUnixSystemBusName: + * + * The #PolkitSystemBusName struct should not be accessed directly. + */ struct _PolkitSystemBusName { GObject parent_instance; @@ -144,12 +149,28 @@ polkit_system_bus_name_class_init (PolkitSystemBusNameClass *klass) } +/** + * polkit_system_bus_name_get_name: + * @system_bus_name: A #PolkitSystemBusName. + * + * Gets the unique system bus name for @system_bus_name. + * + * Returns: The unique system bus name for @system_bus_name. Do not + * free, this string is owned by @system_bus_name. + */ const gchar * polkit_system_bus_name_get_name (PolkitSystemBusName *system_bus_name) { return system_bus_name->name; } +/** + * polkit_system_bus_name_set_name: + * @system_bus_name: A #PolkitSystemBusName. + * @name: A unique system bus name. + * + * Sets the unique system bus name for @system_bus_name. + */ void polkit_system_bus_name_set_name (PolkitSystemBusName *system_bus_name, const gchar *name) @@ -158,6 +179,14 @@ polkit_system_bus_name_set_name (PolkitSystemBusName *system_bus_name, system_bus_name->name = g_strdup (name); } +/** + * polkit_system_bus_name_new: + * @name: A unique system bus name. + * + * Creates a new #PolkitSystemBusName for @name. + * + * Returns: A #PolkitSystemBusName. Free with g_object_unref(). + */ PolkitSubject * polkit_system_bus_name_new (const gchar *name) { diff --git a/src/polkit/polkitunixgroup.c b/src/polkit/polkitunixgroup.c index fc8bf04..79db400 100644 --- a/src/polkit/polkitunixgroup.c +++ b/src/polkit/polkitunixgroup.c @@ -35,9 +35,14 @@ * @title: PolkitUnixGroup * @short_description: Unix groups * - * Encapsulates a UNIX group. + * An object representing a group identity on a UNIX system. */ +/** + * PolkitUnixGroup: + * + * The #PolkitUnixGroup struct should not be accessed directly. + */ struct _PolkitUnixGroup { GObject parent_instance; @@ -136,12 +141,27 @@ polkit_unix_group_class_init (PolkitUnixGroupClass *klass) } +/** + * polkit_unix_group_get_gid: + * @group: A #PolkitUnixGroup. + * + * Gets the UNIX group id for @group. + * + * Returns: A UNIX group id. + */ gid_t polkit_unix_group_get_gid (PolkitUnixGroup *group) { return group->gid; } +/** + * polkit_unix_group_set_gid: + * @group: A #PolkitUnixGroup. + * @gid: A UNIX group id. + * + * Sets @gid for @group. + */ void polkit_unix_group_set_gid (PolkitUnixGroup *group, gid_t gid) @@ -149,6 +169,14 @@ polkit_unix_group_set_gid (PolkitUnixGroup *group, group->gid = gid; } +/** + * polkit_unix_group_new: + * @gid: A UNIX group id. + * + * Creates a new #PolkitUnixGroup object for @gid. + * + * Returns: A #PolkitUnixGroup object. Free with g_object_unref(). + */ PolkitIdentity * polkit_unix_group_new (gid_t gid) { @@ -157,6 +185,16 @@ polkit_unix_group_new (gid_t gid) NULL)); } +/** + * polkit_unix_group_new_for_name: + * @name: A UNIX group name. + * @error: Return location for error. + * + * Creates a new #PolkitUnixGroup object for a group with the group name + * @name. + * + * Returns: A #PolkitUnixGroup object or %NULL if @error is set. + */ PolkitIdentity * polkit_unix_group_new_for_name (const gchar *name, GError **error) diff --git a/src/polkit/polkitunixprocess.c b/src/polkit/polkitunixprocess.c index f3f67de..181f221 100644 --- a/src/polkit/polkitunixprocess.c +++ b/src/polkit/polkitunixprocess.c @@ -34,9 +34,18 @@ * @title: PolkitUnixProcess * @short_description: Unix processs * - * Encapsulates a UNIX process. + * An object for representing a UNIX process. + * + * To uniquely identify processes, both the process id and the start + * time of the process (a monotonic increasing value representing the + * time since the kernel was started) is used. */ +/** + * PolkitUnixProcess: + * + * The #PolkitUnixProcess struct should not be accessed directly. + */ struct _PolkitUnixProcess { GObject parent_instance; @@ -161,18 +170,41 @@ polkit_unix_process_class_init (PolkitUnixProcessClass *klass) } +/** + * polkit_unix_process_get_pid: + * @process: A #PolkitUnixProcess. + * + * Gets the process id for @process. + * + * Returns: The process id for @process. + */ pid_t polkit_unix_process_get_pid (PolkitUnixProcess *process) { return process->pid; } +/** + * polkit_unix_process_get_start_time: + * @process: A #PolkitUnixProcess. + * + * Gets the start time of @process. + * + * Returns: The start time of @process. + */ guint64 polkit_unix_process_get_start_time (PolkitUnixProcess *process) { return process->start_time; } +/** + * polkit_unix_process_set_pid: + * @process: A #PolkitUnixProcess. + * @pid: A process id. + * + * Sets @pid for @process. + */ void polkit_unix_process_set_pid (PolkitUnixProcess *process, pid_t pid) @@ -182,6 +214,17 @@ polkit_unix_process_set_pid (PolkitUnixProcess *process, process->start_time = get_start_time_for_pid (pid); } +/** + * polkit_unix_process_new: + * @pid: The process id. + * + * Creates a new #PolkitUnixProcess for @pid. The start time of the + * process will be looked up in using e.g. the + * /proc filesystem depending on the platform in + * use. + * + * Returns: A #PolkitSubject. Free with g_object_unref(). + */ PolkitSubject * polkit_unix_process_new (pid_t pid) { @@ -190,6 +233,15 @@ polkit_unix_process_new (pid_t pid) NULL)); } +/** + * polkit_unix_process_new_full: + * @pid: The process id. + * @start_time: The start time for @pid. + * + * Creates a new #PolkitUnixProcess object for @pid and @start_time. + * + * Returns: A #PolkitSubject. Free with g_object_unref(). + */ PolkitSubject * polkit_unix_process_new_full (pid_t pid, guint64 start_time) diff --git a/src/polkit/polkitunixsession.c b/src/polkit/polkitunixsession.c index ff0c36a..66c762e 100644 --- a/src/polkit/polkitunixsession.c +++ b/src/polkit/polkitunixsession.c @@ -33,9 +33,16 @@ * @title: PolkitUnixSession * @short_description: Unix sessions * - * Encapsulates a login session on UNIX. + * An object that represents an user session. + * + * The session id is an opaque string obtained from ConsoleKit. */ +/** + * PolkitUnixSession: + * + * The #PolkitUnixSession struct should not be accessed directly. + */ struct _PolkitUnixSession { GObject parent_instance; @@ -132,12 +139,28 @@ polkit_unix_session_class_init (PolkitUnixSessionClass *klass) } +/** + * polkit_unix_session_get_session_id: + * @session: A #PolkitUnixSession. + * + * Gets the session id for @session. + * + * Returns: The session id for @session. Do not free this string, it + * is owned by @session. + **/ const gchar * polkit_unix_session_get_session_id (PolkitUnixSession *session) { return session->session_id; } +/** + * polkit_unix_session_set_session_id: + * @session: A #PolkitUnixSession. + * @session_id: The session id. + * + * Sets the session id for @session to @session_id. + **/ void polkit_unix_session_set_session_id (PolkitUnixSession *session, const gchar *session_id) @@ -146,6 +169,14 @@ polkit_unix_session_set_session_id (PolkitUnixSession *session, session->session_id = g_strdup (session_id); } +/** + * polkit_unix_session_new: + * @session_id: The session id. + * + * Creates a new #PolkitUnixSession for @session_id. + * + * Returns: A #PolkitUnixSession. Free with g_object_unref(). + **/ PolkitSubject * polkit_unix_session_new (const gchar *session_id) { diff --git a/src/polkit/polkitunixuser.c b/src/polkit/polkitunixuser.c index a70d64a..e3d8327 100644 --- a/src/polkit/polkitunixuser.c +++ b/src/polkit/polkitunixuser.c @@ -35,9 +35,14 @@ * @title: PolkitUnixUser * @short_description: Unix users * - * Encapsulates a UNIX user. + * An object representing a user identity on a UNIX system. */ +/** + * PolkitUnixUser: + * + * The #PolkitUnixUser struct should not be accessed directly. + */ struct _PolkitUnixUser { GObject parent_instance; @@ -136,12 +141,27 @@ polkit_unix_user_class_init (PolkitUnixUserClass *klass) } +/** + * polkit_unix_user_get_uid: + * @user: A #PolkitUnixUser. + * + * Gets the UNIX user id for @user. + * + * Returns: A UNIX user id. + */ uid_t polkit_unix_user_get_uid (PolkitUnixUser *user) { return user->uid; } +/** + * polkit_unix_user_set_uid: + * @user: A #PolkitUnixUser. + * @uid: A UNIX user id. + * + * Sets @uid for @user. + */ void polkit_unix_user_set_uid (PolkitUnixUser *user, uid_t uid) @@ -149,6 +169,14 @@ polkit_unix_user_set_uid (PolkitUnixUser *user, user->uid = uid; } +/** + * polkit_unix_user_new: + * @uid: A UNIX user id. + * + * Creates a new #PolkitUnixUser object for @uid. + * + * Returns: A #PolkitUnixUser object. Free with g_object_unref(). + */ PolkitIdentity * polkit_unix_user_new (uid_t uid) { @@ -157,6 +185,16 @@ polkit_unix_user_new (uid_t uid) NULL)); } +/** + * polkit_unix_user_new_for_name: + * @name: A UNIX user name. + * @error: Return location for error. + * + * Creates a new #PolkitUnixUser object for a user with the user name + * @name. + * + * Returns: A #PolkitUnixUser object or %NULL if @error is set. + */ PolkitIdentity * polkit_unix_user_new_for_name (const gchar *name, GError **error)