PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Mon Jun 8 07:56:53 PDT 2009
docs/polkit/polkit-1-sections.txt | 64 ++++++++++----------
src/polkit/polkitactiondescription.c | 104 ++++++++++++++++++++++++++++++++-
src/polkit/polkitauthority.c | 3
src/polkit/polkitauthorizationresult.c | 44 ++++++++-----
src/polkit/polkitdetails.c | 42 +++++++++++++
src/polkit/polkitidentity.c | 44 +++++++++++++
src/polkit/polkitidentity.h | 15 ++++
src/polkit/polkitsubject.c | 45 +++++++++++++-
src/polkit/polkitsubject.h | 15 ++++
src/polkit/polkitsystembusname.c | 33 +++++++++-
src/polkit/polkitunixgroup.c | 40 ++++++++++++
src/polkit/polkitunixprocess.c | 54 ++++++++++++++++-
src/polkit/polkitunixsession.c | 33 ++++++++++
src/polkit/polkitunixuser.c | 40 ++++++++++++
14 files changed, 511 insertions(+), 65 deletions(-)
New commits:
commit b0e8a91269db5270f43d8b213dc3298b12c22a4f
Author: David Zeuthen <davidz at redhat.com>
Date: Mon Jun 8 10:53:36 2009 -0400
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
</SECTION>
<SECTION>
+<FILE>polkitauthority</FILE>
+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
+<SUBSECTION Standard>
+PolkitAuthorityClass
+POLKIT_AUTHORITY
+POLKIT_IS_AUTHORITY
+POLKIT_TYPE_AUTHORITY
+polkit_authority_get_type
+POLKIT_AUTHORITY_CLASS
+POLKIT_IS_AUTHORITY_CLASS
+POLKIT_AUTHORITY_GET_CLASS
+</SECTION>
+
+<SECTION>
<FILE>polkitauthoritymanager</FILE>
PolkitAuthorityManager
polkit_authority_manager_get
@@ -47,37 +78,6 @@ POLKIT_AUTHORITY_MANAGER_GET_CLASS
</SECTION>
<SECTION>
-<FILE>polkitauthority</FILE>
-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
-<SUBSECTION Standard>
-PolkitAuthorityClass
-POLKIT_AUTHORITY
-POLKIT_IS_AUTHORITY
-POLKIT_TYPE_AUTHORITY
-polkit_authority_get_type
-POLKIT_AUTHORITY_CLASS
-POLKIT_IS_AUTHORITY_CLASS
-POLKIT_AUTHORITY_GET_CLASS
-</SECTION>
-
-<SECTION>
<FILE>polkitauthorizationresult</FILE>
PolkitAuthorizationResult
polkit_authorization_result_new
@@ -262,10 +262,10 @@ polkit_implicit_authorization_get_type
<SECTION>
<FILE>polkiterror</FILE>
POLKIT_ERROR
-POLKIT_TYPE_ERROR
PolkitError
<SUBSECTION Standard>
polkit_error_quark
+POLKIT_TYPE_ERROR
polkit_error_get_type
</SECTION>
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 #PolkitIdentity<!-- -->s 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 #PolkitSubject<!-- -->s 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
+ * <filename>/proc</filename> 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)
More information about the hal-commit
mailing list