diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml index b8461f93391ef1216bf0245b432c1109ab1c8be3..4278b29afd31f7dae5b9bface89fd890e792b4ac 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 (MECHANISMS) offering service to unprivileged programs (CLIENTS). See the - PolicyKit-1 manual page for + polkit manual page for the system architecture and big picture. @@ -29,14 +29,26 @@ communicate with the PolicyKit Authority. - Note that clients never use the PolicyKit - API directly – it is intended solely for privileged + Note that clients normally doesn't use the + PolicyKit API directly – it is intended for privileged mechanisms. 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. + + + If a PolicyKit application wants to handle the case where no + authentication agent exists (for example if the app is launched + via a + ssh1 + login), it is trivial for the application to use the PolkitAgentTextListener + class to spawn its own authentication agent as needed. See the + pkcheck or pkexec program sources for an example + of how to do this. As an example of code using the GObject API, see . diff --git a/docs/polkit/polkit-1-sections.txt b/docs/polkit/polkit-1-sections.txt index 85b5d599d5b88a923a698afdbb419c63b40ca18a..78248dcec03bc83db36c636eab726254dc6d760a 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 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 f9f39718cd8c189b30aecde2e57fea96680a75af..404be189d4ecf5cc949d43e2f117402fc63d800c 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 thread-default main + * loop 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 + * thread-default + * main loop 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 + * 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 in the + * thread-default + * main loop 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 + * 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 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 NEVER 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 + * thread-default + * main loop 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 + * thread-default + * main loop 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 + * thread-default + * main loop 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 + * thread-default + * main loop 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 + * thread-default + * main loop 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 + * thread-default + * main loop 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 * org.freedesktop.PolicyKit1 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 35a3ecce2de7b35d23ffdd0d945fcebdb23507aa..01aea78de4ae554865cdbb7d730853c52f55cfe2 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 da908a28e5b3a8c30cbd140e136b27157c8979fd..50491ad9fc81d1eca7f329cdf28e6165958d037a 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 51e60e03d7b72f3de363f23ef491d56870f7fddb..d193eb26dfb1516e93530d2f040fbacfd4398c7b 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 + * thread-default + * main loop 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 9bd074b98a8ac0b0a295eb2232c0337637c7211a..41f2762ac0d00128344fdee0e3d78664efc3552b 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 a72e453cf05b813e2a641f748106bb6a7c68a5d7..c4665618b85829bef4ecda1c1cd11dd87c232b3c 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 + * thread-default + * main loop 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 52d71ffa6af41e10d91897cde47419344548d6c2..5e71ec14afbe64377e683dce4c41c5db966c123c 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 + * MUST not ignore @cancellable; callers of this + * function can and will use it. Additionally, @callback must be + * invoked in the thread-default main + * loop 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 3780b7c3147643c5a5c19c8d2fdacc9b897f6c24..2d72348e783d3e1153083afb4278bfb975086a18 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 thread-default main + * loop 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 30e9540e1161584784421a4e518df6c55db3c930..55eecf5673f1b55a7294602a0e838213f45a2bfa 100644 --- a/src/polkitbackend/polkitbackendactionpool.c +++ b/src/polkitbackend/polkitbackendactionpool.c @@ -30,7 +30,7 @@ #include "polkitbackendactionpool.h" -/** +/* * SECTION:polkitbackendactionpool * @title: PolkitBackendActionPool * @short_description: Registered actions diff --git a/src/polkitbackend/polkitbackendauthority.h b/src/polkitbackend/polkitbackendauthority.h index 7c6dc6d290f5b568575ff87c32d01145fc53fd99..bfc0480ce125db366a3e1068ccadc75f0fe90b91 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 465da9621665e7a48cd37622fc0d079d936b287f..abdb089357e591c9f5bd30cf686f59af480cf062 100644 --- a/src/polkitbackend/polkitbackendconfigsource.c +++ b/src/polkitbackend/polkitbackendconfigsource.c @@ -24,7 +24,7 @@ #include #include "polkitbackendconfigsource.h" -/** +/* * SECTION:polkitbackendconfigsource * @title: PolkitBackendConfigSource * @short_description: Access configuration files diff --git a/src/polkitbackend/polkitbackendinteractiveauthority.c b/src/polkitbackend/polkitbackendinteractiveauthority.c index 31e60df2b2e36dcca40c76c0ac81c2cac1af3c98..386a4c9c02ac0a77ff2d639889fa4065c12ad106 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 b95926984d486261c381274490e6b0e54e62f3ff..20e9682c6659988151f682d864c5724024876c2b 100644 --- a/src/polkitbackend/polkitbackendlocalauthorizationstore.c +++ b/src/polkitbackend/polkitbackendlocalauthorizationstore.c @@ -25,7 +25,7 @@ #include #include "polkitbackendlocalauthorizationstore.h" -/** +/* * 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 877d69e25307671a3047d950f5c901ed7a174604..e91ad84a9b5c5f2204d4704648f95211d287e28d 100644 --- a/src/polkitbackend/polkitbackendsessionmonitor.c +++ b/src/polkitbackend/polkitbackendsessionmonitor.c @@ -31,7 +31,7 @@ #define CKDB_PATH "/var/run/ConsoleKit/database" -/** +/* * SECTION:polkitbackendsessionmonitor * @title: PolkitBackendSessionMonitor * @short_description: Monitor sessions