Commit b0e8a912 authored by David Zeuthen's avatar David Zeuthen

Add some more API docs

parent d2239a6e
......@@ -16,6 +16,37 @@ POLKIT_IS_UNIX_USER_CLASS
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
......@@ -46,37 +77,6 @@ POLKIT_IS_AUTHORITY_MANAGER_CLASS
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
......@@ -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>
......
......@@ -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;
}
......@@ -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.
*/
/**
......
......@@ -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)
{
......
......@@ -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)
{
......
......@@ -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)
......
......@@ -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;
......
......@@ -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;
}
......@@ -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;
......
......@@ -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)
{
......
......@@ -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.