PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Fri Aug 20 09:30:36 PDT 2010
docs/polkit/overview.xml | 24 +-
docs/polkit/polkit-1-sections.txt | 17 -
src/polkit/polkitauthority.c | 145 ++++++++++-----
src/polkit/polkitauthorityfeatures.h | 2
src/polkit/polkitidentity.h | 2
src/polkit/polkitsubject.c | 13 -
src/polkit/polkitsystembusname.c | 3
src/polkit/polkitunixsession.c | 12 -
src/polkitagent/polkitagentlistener.c | 43 ++--
src/polkitagent/polkitagentsession.c | 6
src/polkitbackend/polkitbackendactionpool.c | 2
src/polkitbackend/polkitbackendauthority.h | 7
src/polkitbackend/polkitbackendconfigsource.c | 2
src/polkitbackend/polkitbackendinteractiveauthority.c | 2
src/polkitbackend/polkitbackendlocalauthorizationstore.c | 2
src/polkitbackend/polkitbackendsessionmonitor.c | 2
16 files changed, 190 insertions(+), 94 deletions(-)
New commits:
commit d8e6d66b3f47b32fac5ee690aad8089c0ab293b9
Author: David Zeuthen <davidz at redhat.com>
Date: Fri Aug 20 12:29:18 2010 -0400
Various doc cleanups
Signed-off-by: David Zeuthen <davidz at redhat.com>
diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
index b8461f9..4278b29 100644
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -12,7 +12,7 @@
PolicyKit provides an authorization API intended to be used by
privileged programs (<quote>MECHANISMS</quote>) offering service
to unprivileged programs (<quote>CLIENTS</quote>). See the
- <link linkend="PolicyKit-1.8">PolicyKit-1</link> manual page for
+ <link linkend="polkit.8">polkit</link> manual page for
the system architecture and big picture.
</para>
</chapter>
@@ -29,14 +29,26 @@
communicate with the PolicyKit Authority.
</para>
<para>
- Note that <emphasis>clients</emphasis> never use the PolicyKit
- API directly – it is intended solely for privileged
+ Note that <emphasis>clients</emphasis> normally doesn't use the
+ PolicyKit API directly – it is intended for privileged
<emphasis>mechanisms</emphasis>. If a client needs to disable,
modify or remove UI elements to e.g. convey to the user that a
certain action cannot be carried out (because e.g. the user is
- not authorized) or authentication is needed (by
- e.g. displaying a padlock icon in the UI), the mechanism will
- need to provide API for this.
+ not authorized) or authentication is needed (by e.g. displaying
+ a padlock icon in the UI), it is usually better to have the
+ mechanism provide an API for this.
+ </para>
+ <para>
+ If a PolicyKit application wants to handle the case where no
+ authentication agent exists (for example if the app is launched
+ via a
+ <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ login), it is trivial for the application to use the <link
+ linkend="PolkitAgentTextListener">PolkitAgentTextListener</link>
+ class to spawn its own authentication agent as needed. See the
+ <link linkend="pkcheck.1">pkcheck</link> or <link
+ linkend="pkexec.1">pkexec</link> program sources for an example
+ of how to do this.
</para>
<para>
As an example of code using the GObject API, see <xref linkend="cancel-example"/>.
diff --git a/docs/polkit/polkit-1-sections.txt b/docs/polkit/polkit-1-sections.txt
index 85b5d59..78248dc 100644
--- a/docs/polkit/polkit-1-sections.txt
+++ b/docs/polkit/polkit-1-sections.txt
@@ -21,36 +21,36 @@ POLKIT_UNIX_USER_GET_CLASS
PolkitAuthority
PolkitAuthorityFeatures
PolkitCheckAuthorizationFlags
-polkit_authority_get_sync
polkit_authority_get_async
polkit_authority_get_finish
+polkit_authority_get_sync
polkit_authority_get_owner
polkit_authority_get_backend_name
polkit_authority_get_backend_version
polkit_authority_get_backend_features
polkit_authority_check_authorization
polkit_authority_check_authorization_finish
+polkit_authority_check_authorization_sync
polkit_authority_enumerate_actions
polkit_authority_enumerate_actions_finish
+polkit_authority_enumerate_actions_sync
polkit_authority_register_authentication_agent
polkit_authority_register_authentication_agent_finish
+polkit_authority_register_authentication_agent_sync
polkit_authority_unregister_authentication_agent
polkit_authority_unregister_authentication_agent_finish
+polkit_authority_unregister_authentication_agent_sync
polkit_authority_authentication_agent_response
polkit_authority_authentication_agent_response_finish
+polkit_authority_authentication_agent_response_sync
polkit_authority_enumerate_temporary_authorizations
polkit_authority_enumerate_temporary_authorizations_finish
+polkit_authority_enumerate_temporary_authorizations_sync
polkit_authority_revoke_temporary_authorizations
polkit_authority_revoke_temporary_authorizations_finish
+polkit_authority_revoke_temporary_authorizations_sync
polkit_authority_revoke_temporary_authorization_by_id
polkit_authority_revoke_temporary_authorization_by_id_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
-polkit_authority_enumerate_temporary_authorizations_sync
-polkit_authority_revoke_temporary_authorizations_sync
polkit_authority_revoke_temporary_authorization_by_id_sync
<SUBSECTION Standard>
PolkitAuthorityClass
@@ -282,6 +282,7 @@ polkit_backend_authority_authentication_agent_response
polkit_backend_authority_enumerate_actions
polkit_backend_authority_enumerate_temporary_authorizations
polkit_backend_authority_revoke_temporary_authorizations
+polkit_backend_authority_revoke_temporary_authorization_by_id
polkit_backend_authority_get
polkit_backend_authority_register
polkit_backend_authority_unregister
diff --git a/src/polkit/polkitauthority.c b/src/polkit/polkitauthority.c
index f9f3971..404be18 100644
--- a/src/polkit/polkitauthority.c
+++ b/src/polkit/polkitauthority.c
@@ -449,8 +449,10 @@ authority_get_async_cb (GObject *source_object,
* Asynchronously gets a reference to the authority.
*
* This is an asynchronous failable function. When the result is
- * ready, @callback will be invoked and you can use
- * polkit_authority_get_finish() to get the result. See
+ * ready, @callback will be invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this method from and you
+ * can use polkit_authority_get_finish() to get the result. See
* polkit_authority_get_sync() for the synchronous version.
*/
void
@@ -534,8 +536,9 @@ polkit_authority_get_finish (GAsyncResult *res,
*
* Synchronously gets a reference to the authority.
*
- * This is a synchronous failable function. See
- * polkit_authority_get_async() for the synchronous version.
+ * This is a synchronous failable function - the calling thread is
+ * blocked until a reply is received. See polkit_authority_get_async()
+ * for the asynchronous version.
*
* Returns: A #PolkitAuthority. Free it with g_object_unref() when
* done with it.
@@ -633,9 +636,11 @@ generic_async_cb (GObject *source_obj,
*
* Asynchronously retrieves all registered actions.
*
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_enumerate_actions_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call polkit_authority_enumerate_actions_finish()
+ * to get the result of the operation.
**/
void
polkit_authority_enumerate_actions (PolkitAuthority *authority,
@@ -717,7 +722,9 @@ polkit_authority_enumerate_actions_finish (PolkitAuthority *authority,
* @cancellable: (allow-none): A #GCancellable or %NULL.
* @error: (allow-none): Return location for error or %NULL.
*
- * Synchronously retrieves all registered actions.
+ * Synchronously retrieves all registered actions - the calling thread
+ * is blocked until a reply is received. See
+ * polkit_authority_enumerate_actions() for the asynchronous version.
*
* Returns: A list of #PolkitActionDescription or %NULL if @error is set. The returned list
* should be freed with g_list_free() after each element have been freed with g_object_unref().
@@ -838,13 +845,17 @@ check_authorization_cb (GDBusProxy *proxy,
* Asynchronously checks if @subject is authorized to perform the action represented
* by @action_id.
*
- * Note that #POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
- * SHOULD be passed ONLY if the event that triggered the authorization
- * check is stemming from an user action, e.g. the user pressing a
- * button or attaching a device.
- *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_check_authorization_finish() to get the result of
+ * Note that %POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
+ * <emphasis>SHOULD</emphasis> be passed <emphasis>ONLY</emphasis> if
+ * the event that triggered the authorization check is stemming from
+ * an user action, e.g. the user pressing a button or attaching a
+ * device.
+ *
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_check_authorization_finish() to get the result of
* the operation.
**/
void
@@ -944,12 +955,22 @@ polkit_authority_check_authorization_finish (PolkitAuthority *authority
* @cancellable: (allow-none): A #GCancellable or %NULL.
* @error: (allow-none): Return location for error or %NULL.
*
- * Checks if @subject is authorized to perform the action represented by @action_id.
+ * Checks if @subject is authorized to perform the action represented
+ * by @action_id.
+ *
+ * Note that %POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
+ * <emphasis>SHOULD</emphasis> be passed <emphasis>ONLY</emphasis> if
+ * the event that triggered the authorization check is stemming from
+ * an user action, e.g. the user pressing a button or attaching a
+ * device.
*
- * Note that #POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
- * SHOULD be passed ONLY if the event that triggered the authorization
- * check is stemming from an user action, e.g. the user pressing a
- * button or attaching a device.
+ * Note the calling thread is blocked until a reply is received. You
+ * should therefore <emphasis>NEVER</emphasis> do this from a GUI
+ * thread or a daemon service thread when using the
+ * %POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION flag. This
+ * is because it may potentially take minutes (or even hours) for the
+ * operation to complete because it involves waiting for the user to
+ * authenticate.
*
* Returns: A #PolkitAuthorizationResult or %NULL if @error is set. Free with g_object_unref().
*/
@@ -995,9 +1016,12 @@ polkit_authority_check_authorization_sync (PolkitAuthority *author
*
* Asynchronously registers an authentication agent.
*
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_register_authentication_agent_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_register_authentication_agent_finish() to get the
+ * result of the operation.
**/
void
polkit_authority_register_authentication_agent (PolkitAuthority *authority,
@@ -1083,7 +1107,10 @@ polkit_authority_register_authentication_agent_finish (PolkitAuthority *authorit
* @cancellable: (allow-none): A #GCancellable or %NULL.
* @error: (allow-none): Return location for error or %NULL.
*
- * Registers an authentication agent.
+ * Registers an authentication agent. The calling thread is blocked
+ * until a reply is received. See
+ * polkit_authority_register_authentication_agent() for the
+ * asynchronous version.
*
* Returns: %TRUE if the authentication agent was successfully registered, %FALSE if @error is set.
**/
@@ -1120,7 +1147,6 @@ polkit_authority_register_authentication_agent_sync (PolkitAuthority *author
* polkit_authority_unregister_authentication_agent:
* @authority: A #PolkitAuthority.
* @subject: The subject the authentication agent is for, typically a #PolkitUnixSession object.
- * @locale: The locale of the authentication agent.
* @object_path: The object path for the authentication agent.
* @cancellable: (allow-none): A #GCancellable or %NULL.
* @callback: A #GAsyncReadyCallback to call when the request is satisfied.
@@ -1128,9 +1154,12 @@ polkit_authority_register_authentication_agent_sync (PolkitAuthority *author
*
* Asynchronously unregisters an authentication agent.
*
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_unregister_authentication_agent_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_unregister_authentication_agent_finish() to get
+ * the result of the operation.
**/
void
polkit_authority_unregister_authentication_agent (PolkitAuthority *authority,
@@ -1208,12 +1237,14 @@ polkit_authority_unregister_authentication_agent_finish (PolkitAuthority *author
* polkit_authority_unregister_authentication_agent_sync:
* @authority: A #PolkitAuthority.
* @subject: The subject the authentication agent is for, typically a #PolkitUnixSession object.
- * @locale: The locale of the authentication agent.
* @object_path: The object path for the authentication agent.
* @cancellable: (allow-none): A #GCancellable or %NULL.
* @error: (allow-none): Return location for error or %NULL.
*
- * Unregisters an authentication agent.
+ * Unregisters an authentication agent. The calling thread is blocked
+ * until a reply is received. See
+ * polkit_authority_unregister_authentication_agent() for the
+ * asynchronous version.
*
* Returns: %TRUE if the authentication agent was successfully unregistered, %FALSE if @error is set.
**/
@@ -1259,9 +1290,12 @@ polkit_authority_unregister_authentication_agent_sync (PolkitAuthority *auth
* This function is only used by the privileged bits of an authentication agent.
* It will fail if the caller is not sufficiently privileged (typically uid 0).
*
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_authentication_agent_response_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_authentication_agent_response_finish() to get the
+ * result of the operation.
**/
void
polkit_authority_authentication_agent_response (PolkitAuthority *authority,
@@ -1347,6 +1381,10 @@ polkit_authority_authentication_agent_response_finish (PolkitAuthority *authorit
* authentication request identified by @cookie. See polkit_authority_authentication_agent_response()
* for limitations on who is allowed is to call this method.
*
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_authentication_agent_response() for the
+ * asynchronous version.
+ *
* Returns: %TRUE if @authority acknowledged the call, %FALSE if @error is set.
**/
gboolean
@@ -1386,9 +1424,12 @@ polkit_authority_authentication_agent_response_sync (PolkitAuthority *author
*
* Asynchronously gets all temporary authorizations for @subject.
*
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_enumerate_temporary_authorizations_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_enumerate_temporary_authorizations_finish() to get
+ * the result of the operation.
**/
void
polkit_authority_enumerate_temporary_authorizations (PolkitAuthority *authority,
@@ -1489,6 +1530,10 @@ polkit_authority_enumerate_temporary_authorizations_finish (PolkitAuthority *aut
*
* Synchronousky gets all temporary authorizations for @subject.
*
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_enumerate_temporary_authorizations() for the
+ * asynchronous version.
+ *
* Returns: A list of #PolkitTemporaryAuthorization objects or %NULL if @error is set. The returned list
* should be freed with g_list_free() after each element have been freed with g_object_unref().
**/
@@ -1527,9 +1572,12 @@ polkit_authority_enumerate_temporary_authorizations_sync (PolkitAuthority *a
*
* Asynchronously revokes all temporary authorizations for @subject.
*
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_revoke_temporary_authorizations_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_revoke_temporary_authorizations_finish() to get
+ * the result of the operation.
**/
void
polkit_authority_revoke_temporary_authorizations (PolkitAuthority *authority,
@@ -1608,6 +1656,10 @@ polkit_authority_revoke_temporary_authorizations_finish (PolkitAuthority *author
*
* Synchronously revokes all temporary authorization from @subject.
*
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_revoke_temporary_authorizations() for the
+ * asynchronous version.
+ *
* Returns: %TRUE if the temporary authorization was revoked, %FALSE if error is set.
**/
gboolean
@@ -1645,9 +1697,12 @@ polkit_authority_revoke_temporary_authorizations_sync (PolkitAuthority *auth
*
* Asynchronously revoke a temporary authorization.
*
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_revoke_temporary_authorization_by_id_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_revoke_temporary_authorization_by_id_finish() to
+ * get the result of the operation.
*/
void
polkit_authority_revoke_temporary_authorization_by_id (PolkitAuthority *authority,
@@ -1721,6 +1776,10 @@ polkit_authority_revoke_temporary_authorization_by_id_finish (PolkitAuthority *a
*
* Synchronously revokes a temporary authorization.
*
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_revoke_temporary_authorization_by_id() for the
+ * asynchronous version.
+ *
* Returns: %TRUE if the temporary authorization was revoked, %FALSE if error is set.
**/
gboolean
@@ -1755,7 +1814,7 @@ polkit_authority_revoke_temporary_authorization_by_id_sync (PolkitAuthority
* The unique name on the system message bus of the owner of the name
* <literal>org.freedesktop.PolicyKit1</literal> or %NULL if no-one
* currently owns the name. You may connect to the #GObject::notify
- * signal to track changes to the #PolkitAuthority::owner property.
+ * signal to track changes to the #PolkitAuthority:owner property.
*
* Returns: (allow-none): %NULL or a string that should be freed with g_free().
**/
diff --git a/src/polkit/polkitauthorityfeatures.h b/src/polkit/polkitauthorityfeatures.h
index 35a3ecc..01aea78 100644
--- a/src/polkit/polkitauthorityfeatures.h
+++ b/src/polkit/polkitauthorityfeatures.h
@@ -35,7 +35,6 @@ G_BEGIN_DECLS
* @POLKIT_AUTHORITY_FEATURES_NONE: No flags set.
* @POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION: The authority supports temporary authorizations
* that can be obtained through authentication.
- * @POLKIT_AUTHORITY_FEATURES_LOCKDOWN: The authority supports the XXX method.
*
* Flags describing features supported by the Authority implementation.
*/
@@ -43,7 +42,6 @@ typedef enum
{
POLKIT_AUTHORITY_FEATURES_NONE = 0,
POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION = (1<<0),
- POLKIT_AUTHORITY_FEATURES_LOCKDOWN = (1<<1)
} PolkitAuthorityFeatures;
G_END_DECLS
diff --git a/src/polkit/polkitidentity.h b/src/polkit/polkitidentity.h
index da908a2..50491ad 100644
--- a/src/polkit/polkitidentity.h
+++ b/src/polkit/polkitidentity.h
@@ -70,7 +70,7 @@ struct _PolkitIdentityIface
};
GType polkit_identity_get_type (void) G_GNUC_CONST;
-guint polkit_identity_hash (PolkitIdentity *a);
+guint polkit_identity_hash (PolkitIdentity *identity);
gboolean polkit_identity_equal (PolkitIdentity *a,
PolkitIdentity *b);
gchar *polkit_identity_to_string (PolkitIdentity *identity);
diff --git a/src/polkit/polkitsubject.c b/src/polkit/polkitsubject.c
index 51e60e0..d193eb2 100644
--- a/src/polkit/polkitsubject.c
+++ b/src/polkit/polkitsubject.c
@@ -140,9 +140,11 @@ polkit_subject_to_string (PolkitSubject *subject)
*
* Asynchronously checks if @subject exists.
*
- * When the operation is finished, @callback will be invoked. You can
- * then call polkit_subject_exists_finish() to get the result of the
- * operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call polkit_subject_exists_finish() to get the
+ * result of the operation.
**/
void
polkit_subject_exists (PolkitSubject *subject,
@@ -189,8 +191,9 @@ polkit_subject_exists_finish (PolkitSubject *subject,
*
* Checks if @subject exists.
*
- * This is a synchronous blocking call, see polkit_subject_exists()
- * for the asynchronous version.
+ * This is a synchronous blocking call - the calling thread is blocked
+ * until a reply is received. See polkit_subject_exists() for the
+ * asynchronous version.
*
* Returns: %TRUE if the subject exists, %FALSE if not or @error is set.
*/
diff --git a/src/polkit/polkitsystembusname.c b/src/polkit/polkitsystembusname.c
index 9bd074b..41f2762 100644
--- a/src/polkit/polkitsystembusname.c
+++ b/src/polkit/polkitsystembusname.c
@@ -346,7 +346,8 @@ subject_iface_init (PolkitSubjectIface *subject_iface)
* @cancellable: (allow-none): A #GCancellable or %NULL.
* @error: (allow-none): Return location for error or %NULL.
*
- * Synchronously gets a #PolkitUnixProcess object for @system_bus_name.
+ * Synchronously gets a #PolkitUnixProcess object for @system_bus_name
+ * - the calling thread is blocked until a reply is received.
*
* Returns: (allow-none): A #PolkitUnixProcess object or %NULL if @error is set.
**/
diff --git a/src/polkit/polkitunixsession.c b/src/polkit/polkitunixsession.c
index a72e453..c466561 100644
--- a/src/polkit/polkitunixsession.c
+++ b/src/polkit/polkitunixsession.c
@@ -242,9 +242,12 @@ polkit_unix_session_new (const gchar *session_id)
* Asynchronously creates a new #PolkitUnixSession object for the
* process with process id @pid.
*
- * When the operation is finished, @callback will be invoked. You can
- * then call polkit_unix_session_new_for_process_finish() to get the
- * result of the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_unix_session_new_for_process_finish() to get the result of
+ * the operation.
*
* This method constructs the object asynchronously, for the synchronous and blocking version
* use polkit_unix_session_new_for_process_sync().
@@ -305,7 +308,8 @@ polkit_unix_session_new_for_process_finish (GAsyncResult *res,
*
* Creates a new #PolkitUnixSession for the process with process id @pid.
*
- * This is a synchronous call that does blocking IO, for the asynchronous version, use
+ * This is a synchronous call - the calling thread is blocked until a
+ * reply is received. For the asynchronous version, see
* polkit_unix_session_new_for_process().
*
* Returns: (allow-none): A #PolkitUnixSession for @pid or %NULL if
diff --git a/src/polkitagent/polkitagentlistener.c b/src/polkitagent/polkitagentlistener.c
index 52d71ff..5e71ec1 100644
--- a/src/polkitagent/polkitagentlistener.c
+++ b/src/polkitagent/polkitagentlistener.c
@@ -33,15 +33,17 @@
*
* #PolkitAgentListener is an abstract base class used for implementing authentication
* agents. To implement an authentication agent, simply subclass #PolkitAgentListener and
- * implement the @initiate_authentication and @initiate_authentication_finish VFuncs.
+ * implement the @initiate_authentication and @initiate_authentication_finish methods.
*
- * Typically authentication agents use #PolkitAgentSession to authenticate users (via
- * passwords) and communicate back the authentication result to the PolicyKit daemon.
- * This is however not requirement. Depending on the system an authentication agent
- * may use other means (such as a Yes/No dialog) to obtain sufficient evidence that
- * the user is one of the requested identities.
+ * Typically authentication agents use #PolkitAgentSession to
+ * authenticate users (via passwords) and communicate back the
+ * authentication result to the PolicyKit daemon. This is however not
+ * requirement. Depending on the system an authentication agent may
+ * use other means (such as a Yes/No dialog) to obtain sufficient
+ * evidence that the user is one of the requested identities.
*
- * To register a #PolkitAgentListener with the PolicyKit daemon, use polkit_agent_register_listener().
+ * To register a #PolkitAgentListener with the PolicyKit daemon, use
+ * polkit_agent_listener_register().
*/
typedef struct
@@ -381,6 +383,8 @@ server_thread_func (gpointer user_data)
* example another authentication agent may already be registered for
* @subject.
*
+ * Note that the calling thread is blocked until a reply is received.
+ *
* Returns: %NULL if @error is set, otherwise a registration handle
* that can be used with polkit_agent_listener_unregister().
*/
@@ -703,17 +707,24 @@ polkit_agent_listener_class_init (PolkitAgentListenerClass *klass)
* @callback: Function to call when the user is done authenticating.
* @user_data: Data to pass to @callback.
*
- * Called on a registered authentication agent (see polkit_agent_register_listener()) when
- * the user owning the session needs to prove he is one of the identities listed in @identities.
+ * Called on a registered authentication agent (see
+ * polkit_agent_listener_register()) when the user owning the session
+ * needs to prove he is one of the identities listed in @identities.
*
- * When the user is done authenticating (for example by dismissing an authentication dialog
- * or by successfully entering a password or otherwise proving the user is one of the
- * identities in @identities), @callback will be invoked. The caller then calls
- * polkit_agent_listener_initiate_authentication_finish() to get the result.
+ * When the user is done authenticating (for example by dismissing an
+ * authentication dialog or by successfully entering a password or
+ * otherwise proving the user is one of the identities in
+ * @identities), @callback will be invoked. The caller then calls
+ * polkit_agent_listener_initiate_authentication_finish() to get the
+ * result.
*
- * #PolkitAgentListener derived subclasses imlementing this method MUST not
- * ignore @cancellable; callers of this function can and will use it.
- **/
+ * #PolkitAgentListener derived subclasses imlementing this method
+ * <emphasis>MUST</emphasis> not ignore @cancellable; callers of this
+ * function can and will use it. Additionally, @callback must be
+ * invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread that this method is called from.
+ */
void
polkit_agent_listener_initiate_authentication (PolkitAgentListener *listener,
const gchar *action_id,
diff --git a/src/polkitagent/polkitagentsession.c b/src/polkitagent/polkitagentsession.c
index 3780b7c..2d72348 100644
--- a/src/polkitagent/polkitagentsession.c
+++ b/src/polkitagent/polkitagentsession.c
@@ -429,7 +429,11 @@ polkit_agent_session_response (PolkitAgentSession *session,
* polkit_agent_session_initiate:
* @session: A #PolkitAgentSession.
*
- * Initiates the authentication session.
+ * Initiates the authentication session. Before calling this method,
+ * make sure to connect to the various signals. The signals will be
+ * emitted in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> that this method is invoked from.
*
* Use polkit_agent_session_cancel() to cancel the session.
**/
diff --git a/src/polkitbackend/polkitbackendactionpool.c b/src/polkitbackend/polkitbackendactionpool.c
index 30e9540..55eecf5 100644
--- a/src/polkitbackend/polkitbackendactionpool.c
+++ b/src/polkitbackend/polkitbackendactionpool.c
@@ -30,7 +30,7 @@
#include "polkitbackendactionpool.h"
-/**
+/* <internal>
* SECTION:polkitbackendactionpool
* @title: PolkitBackendActionPool
* @short_description: Registered actions
diff --git a/src/polkitbackend/polkitbackendauthority.h b/src/polkitbackend/polkitbackendauthority.h
index 7c6dc6d..bfc0480 100644
--- a/src/polkitbackend/polkitbackendauthority.h
+++ b/src/polkitbackend/polkitbackendauthority.h
@@ -62,7 +62,10 @@ struct _PolkitBackendAuthority
/**
* PolkitBackendAuthorityClass:
* @parent_class: The parent class.
- * @changed: Function pointer for #PolkitBackendAuthorityClass::changed signal.
+ * @get_name: Function pointer for the polkit_backend_authority_get_name() function.
+ * @get_version: Function pointer for the polkit_backend_authority_get_version() function.
+ * @get_features: Function pointer for the polkit_backend_authority_get_features() function.
+ * @changed: Function pointer for #PolkitBackendAuthority::changed signal.
* @enumerate_actions: Enumerates registered actions on the
* system. See polkit_backend_authority_enumerate_actions() for
* details.
@@ -100,7 +103,7 @@ struct _PolkitBackendAuthority
* the operation. See polkit_backend_authority_revoke_temporary_authorization_by_id()
* for details.
*
- * VFuncs that authority backends need to implement.
+ * Class structure for #PolkitBackendAuthority.
*/
struct _PolkitBackendAuthorityClass
{
diff --git a/src/polkitbackend/polkitbackendconfigsource.c b/src/polkitbackend/polkitbackendconfigsource.c
index 465da96..abdb089 100644
--- a/src/polkitbackend/polkitbackendconfigsource.c
+++ b/src/polkitbackend/polkitbackendconfigsource.c
@@ -24,7 +24,7 @@
#include <polkit/polkit.h>
#include "polkitbackendconfigsource.h"
-/**
+/* <internal>
* SECTION:polkitbackendconfigsource
* @title: PolkitBackendConfigSource
* @short_description: Access configuration files
diff --git a/src/polkitbackend/polkitbackendinteractiveauthority.c b/src/polkitbackend/polkitbackendinteractiveauthority.c
index 31e60df..386a4c9 100644
--- a/src/polkitbackend/polkitbackendinteractiveauthority.c
+++ b/src/polkitbackend/polkitbackendinteractiveauthority.c
@@ -1138,7 +1138,7 @@ check_authorization_sync (PolkitBackendAuthority *authority,
*
* The default implementation returns a list with a single element for the super user.
*
- * Returns: A list of #PolkitIdentities. Free each element
+ * Returns: A list of #PolkitIdentity objects. Free each element
* g_object_unref(), then free the list with g_list_free().
*/
GList *
diff --git a/src/polkitbackend/polkitbackendlocalauthorizationstore.c b/src/polkitbackend/polkitbackendlocalauthorizationstore.c
index b959269..20e9682 100644
--- a/src/polkitbackend/polkitbackendlocalauthorizationstore.c
+++ b/src/polkitbackend/polkitbackendlocalauthorizationstore.c
@@ -25,7 +25,7 @@
#include <polkit/polkit.h>
#include "polkitbackendlocalauthorizationstore.h"
-/**
+/* <internal>
* SECTION:polkitbackendlocalauthorizationstore
* @title: PolkitBackendLocalAuthorizationStore
* @short_description: Watches a directory for authorization files
diff --git a/src/polkitbackend/polkitbackendsessionmonitor.c b/src/polkitbackend/polkitbackendsessionmonitor.c
index 877d69e..e91ad84 100644
--- a/src/polkitbackend/polkitbackendsessionmonitor.c
+++ b/src/polkitbackend/polkitbackendsessionmonitor.c
@@ -31,7 +31,7 @@
#define CKDB_PATH "/var/run/ConsoleKit/database"
-/**
+/* <internal>
* SECTION:polkitbackendsessionmonitor
* @title: PolkitBackendSessionMonitor
* @short_description: Monitor sessions
More information about the hal-commit
mailing list