Commit d8e6d66b authored by David Zeuthen's avatar David Zeuthen

Various doc cleanups

Signed-off-by: default avatarDavid Zeuthen <davidz@redhat.com>
parent 536765bc
...@@ -12,7 +12,7 @@ ...@@ -12,7 +12,7 @@
PolicyKit provides an authorization API intended to be used by PolicyKit provides an authorization API intended to be used by
privileged programs (<quote>MECHANISMS</quote>) offering service privileged programs (<quote>MECHANISMS</quote>) offering service
to unprivileged programs (<quote>CLIENTS</quote>). See the 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. the system architecture and big picture.
</para> </para>
</chapter> </chapter>
...@@ -29,14 +29,26 @@ ...@@ -29,14 +29,26 @@
communicate with the PolicyKit Authority. communicate with the PolicyKit Authority.
</para> </para>
<para> <para>
Note that <emphasis>clients</emphasis> never use the PolicyKit Note that <emphasis>clients</emphasis> normally doesn't use the
API directly – it is intended solely for privileged PolicyKit API directly – it is intended for privileged
<emphasis>mechanisms</emphasis>. If a client needs to disable, <emphasis>mechanisms</emphasis>. If a client needs to disable,
modify or remove UI elements to e.g. convey to the user that a 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 certain action cannot be carried out (because e.g. the user is
not authorized) or authentication is needed (by not authorized) or authentication is needed (by e.g. displaying
e.g. displaying a padlock icon in the UI), the mechanism will a padlock icon in the UI), it is usually better to have the
need to provide API for this. 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>
<para> <para>
As an example of code using the GObject API, see <xref linkend="cancel-example"/>. As an example of code using the GObject API, see <xref linkend="cancel-example"/>.
......
...@@ -21,36 +21,36 @@ POLKIT_UNIX_USER_GET_CLASS ...@@ -21,36 +21,36 @@ POLKIT_UNIX_USER_GET_CLASS
PolkitAuthority PolkitAuthority
PolkitAuthorityFeatures PolkitAuthorityFeatures
PolkitCheckAuthorizationFlags PolkitCheckAuthorizationFlags
polkit_authority_get_sync
polkit_authority_get_async polkit_authority_get_async
polkit_authority_get_finish polkit_authority_get_finish
polkit_authority_get_sync
polkit_authority_get_owner polkit_authority_get_owner
polkit_authority_get_backend_name polkit_authority_get_backend_name
polkit_authority_get_backend_version polkit_authority_get_backend_version
polkit_authority_get_backend_features polkit_authority_get_backend_features
polkit_authority_check_authorization polkit_authority_check_authorization
polkit_authority_check_authorization_finish polkit_authority_check_authorization_finish
polkit_authority_check_authorization_sync
polkit_authority_enumerate_actions polkit_authority_enumerate_actions
polkit_authority_enumerate_actions_finish polkit_authority_enumerate_actions_finish
polkit_authority_enumerate_actions_sync
polkit_authority_register_authentication_agent polkit_authority_register_authentication_agent
polkit_authority_register_authentication_agent_finish polkit_authority_register_authentication_agent_finish
polkit_authority_register_authentication_agent_sync
polkit_authority_unregister_authentication_agent polkit_authority_unregister_authentication_agent
polkit_authority_unregister_authentication_agent_finish polkit_authority_unregister_authentication_agent_finish
polkit_authority_unregister_authentication_agent_sync
polkit_authority_authentication_agent_response polkit_authority_authentication_agent_response
polkit_authority_authentication_agent_response_finish polkit_authority_authentication_agent_response_finish
polkit_authority_authentication_agent_response_sync
polkit_authority_enumerate_temporary_authorizations polkit_authority_enumerate_temporary_authorizations
polkit_authority_enumerate_temporary_authorizations_finish polkit_authority_enumerate_temporary_authorizations_finish
polkit_authority_enumerate_temporary_authorizations_sync
polkit_authority_revoke_temporary_authorizations polkit_authority_revoke_temporary_authorizations
polkit_authority_revoke_temporary_authorizations_finish 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
polkit_authority_revoke_temporary_authorization_by_id_finish 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 polkit_authority_revoke_temporary_authorization_by_id_sync
<SUBSECTION Standard> <SUBSECTION Standard>
PolkitAuthorityClass PolkitAuthorityClass
...@@ -282,6 +282,7 @@ polkit_backend_authority_authentication_agent_response ...@@ -282,6 +282,7 @@ polkit_backend_authority_authentication_agent_response
polkit_backend_authority_enumerate_actions polkit_backend_authority_enumerate_actions
polkit_backend_authority_enumerate_temporary_authorizations polkit_backend_authority_enumerate_temporary_authorizations
polkit_backend_authority_revoke_temporary_authorizations polkit_backend_authority_revoke_temporary_authorizations
polkit_backend_authority_revoke_temporary_authorization_by_id
polkit_backend_authority_get polkit_backend_authority_get
polkit_backend_authority_register polkit_backend_authority_register
polkit_backend_authority_unregister polkit_backend_authority_unregister
......
This diff is collapsed.
...@@ -35,7 +35,6 @@ G_BEGIN_DECLS ...@@ -35,7 +35,6 @@ G_BEGIN_DECLS
* @POLKIT_AUTHORITY_FEATURES_NONE: No flags set. * @POLKIT_AUTHORITY_FEATURES_NONE: No flags set.
* @POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION: The authority supports temporary authorizations * @POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION: The authority supports temporary authorizations
* that can be obtained through authentication. * that can be obtained through authentication.
* @POLKIT_AUTHORITY_FEATURES_LOCKDOWN: The authority supports the XXX method.
* *
* Flags describing features supported by the Authority implementation. * Flags describing features supported by the Authority implementation.
*/ */
...@@ -43,7 +42,6 @@ typedef enum ...@@ -43,7 +42,6 @@ typedef enum
{ {
POLKIT_AUTHORITY_FEATURES_NONE = 0, POLKIT_AUTHORITY_FEATURES_NONE = 0,
POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION = (1<<0), POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION = (1<<0),
POLKIT_AUTHORITY_FEATURES_LOCKDOWN = (1<<1)
} PolkitAuthorityFeatures; } PolkitAuthorityFeatures;
G_END_DECLS G_END_DECLS
......
...@@ -70,7 +70,7 @@ struct _PolkitIdentityIface ...@@ -70,7 +70,7 @@ struct _PolkitIdentityIface
}; };
GType polkit_identity_get_type (void) G_GNUC_CONST; 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, gboolean polkit_identity_equal (PolkitIdentity *a,
PolkitIdentity *b); PolkitIdentity *b);
gchar *polkit_identity_to_string (PolkitIdentity *identity); gchar *polkit_identity_to_string (PolkitIdentity *identity);
......
...@@ -140,9 +140,11 @@ polkit_subject_to_string (PolkitSubject *subject) ...@@ -140,9 +140,11 @@ polkit_subject_to_string (PolkitSubject *subject)
* *
* Asynchronously checks if @subject exists. * Asynchronously checks if @subject exists.
* *
* When the operation is finished, @callback will be invoked. You can * When the operation is finished, @callback will be invoked in the
* then call polkit_subject_exists_finish() to get the result of the * <link linkend="g-main-context-push-thread-default">thread-default
* operation. * 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 void
polkit_subject_exists (PolkitSubject *subject, polkit_subject_exists (PolkitSubject *subject,
...@@ -189,8 +191,9 @@ polkit_subject_exists_finish (PolkitSubject *subject, ...@@ -189,8 +191,9 @@ polkit_subject_exists_finish (PolkitSubject *subject,
* *
* Checks if @subject exists. * Checks if @subject exists.
* *
* This is a synchronous blocking call, see polkit_subject_exists() * This is a synchronous blocking call - the calling thread is blocked
* for the asynchronous version. * 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. * Returns: %TRUE if the subject exists, %FALSE if not or @error is set.
*/ */
......
...@@ -346,7 +346,8 @@ subject_iface_init (PolkitSubjectIface *subject_iface) ...@@ -346,7 +346,8 @@ subject_iface_init (PolkitSubjectIface *subject_iface)
* @cancellable: (allow-none): A #GCancellable or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL.
* @error: (allow-none): Return location for error 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. * Returns: (allow-none): A #PolkitUnixProcess object or %NULL if @error is set.
**/ **/
......
...@@ -242,9 +242,12 @@ polkit_unix_session_new (const gchar *session_id) ...@@ -242,9 +242,12 @@ polkit_unix_session_new (const gchar *session_id)
* Asynchronously creates a new #PolkitUnixSession object for the * Asynchronously creates a new #PolkitUnixSession object for the
* process with process id @pid. * process with process id @pid.
* *
* When the operation is finished, @callback will be invoked. You can * When the operation is finished, @callback will be invoked in the
* then call polkit_unix_session_new_for_process_finish() to get the * <link linkend="g-main-context-push-thread-default">thread-default
* result of the operation. * 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 * This method constructs the object asynchronously, for the synchronous and blocking version
* use polkit_unix_session_new_for_process_sync(). * use polkit_unix_session_new_for_process_sync().
...@@ -305,7 +308,8 @@ polkit_unix_session_new_for_process_finish (GAsyncResult *res, ...@@ -305,7 +308,8 @@ polkit_unix_session_new_for_process_finish (GAsyncResult *res,
* *
* Creates a new #PolkitUnixSession for the process with process id @pid. * 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(). * polkit_unix_session_new_for_process().
* *
* Returns: (allow-none): A #PolkitUnixSession for @pid or %NULL if * Returns: (allow-none): A #PolkitUnixSession for @pid or %NULL if
......
...@@ -33,15 +33,17 @@ ...@@ -33,15 +33,17 @@
* *
* #PolkitAgentListener is an abstract base class used for implementing authentication * #PolkitAgentListener is an abstract base class used for implementing authentication
* agents. To implement an authentication agent, simply subclass #PolkitAgentListener and * 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 * Typically authentication agents use #PolkitAgentSession to
* passwords) and communicate back the authentication result to the PolicyKit daemon. * authenticate users (via passwords) and communicate back the
* This is however not requirement. Depending on the system an authentication agent * authentication result to the PolicyKit daemon. This is however not
* may use other means (such as a Yes/No dialog) to obtain sufficient evidence that * requirement. Depending on the system an authentication agent may
* the user is one of the requested identities. * 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 typedef struct
...@@ -381,6 +383,8 @@ server_thread_func (gpointer user_data) ...@@ -381,6 +383,8 @@ server_thread_func (gpointer user_data)
* example another authentication agent may already be registered for * example another authentication agent may already be registered for
* @subject. * @subject.
* *
* Note that the calling thread is blocked until a reply is received.
*
* Returns: %NULL if @error is set, otherwise a registration handle * Returns: %NULL if @error is set, otherwise a registration handle
* that can be used with polkit_agent_listener_unregister(). * that can be used with polkit_agent_listener_unregister().
*/ */
...@@ -703,17 +707,24 @@ polkit_agent_listener_class_init (PolkitAgentListenerClass *klass) ...@@ -703,17 +707,24 @@ polkit_agent_listener_class_init (PolkitAgentListenerClass *klass)
* @callback: Function to call when the user is done authenticating. * @callback: Function to call when the user is done authenticating.
* @user_data: Data to pass to @callback. * @user_data: Data to pass to @callback.
* *
* Called on a registered authentication agent (see polkit_agent_register_listener()) when * Called on a registered authentication agent (see
* the user owning the session needs to prove he is one of the identities listed in @identities. * 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 * When the user is done authenticating (for example by dismissing an
* or by successfully entering a password or otherwise proving the user is one of the * authentication dialog or by successfully entering a password or
* identities in @identities), @callback will be invoked. The caller then calls * otherwise proving the user is one of the identities in
* polkit_agent_listener_initiate_authentication_finish() to get the result. * @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 * #PolkitAgentListener derived subclasses imlementing this method
* ignore @cancellable; callers of this function can and will use it. * <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 void
polkit_agent_listener_initiate_authentication (PolkitAgentListener *listener, polkit_agent_listener_initiate_authentication (PolkitAgentListener *listener,
const gchar *action_id, const gchar *action_id,
......
...@@ -429,7 +429,11 @@ polkit_agent_session_response (PolkitAgentSession *session, ...@@ -429,7 +429,11 @@ polkit_agent_session_response (PolkitAgentSession *session,
* polkit_agent_session_initiate: * polkit_agent_session_initiate:
* @session: A #PolkitAgentSession. * @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. * Use polkit_agent_session_cancel() to cancel the session.
**/ **/
......
...@@ -30,7 +30,7 @@ ...@@ -30,7 +30,7 @@
#include "polkitbackendactionpool.h" #include "polkitbackendactionpool.h"
/** /* <internal>
* SECTION:polkitbackendactionpool * SECTION:polkitbackendactionpool
* @title: PolkitBackendActionPool * @title: PolkitBackendActionPool
* @short_description: Registered actions * @short_description: Registered actions
......
...@@ -62,7 +62,10 @@ struct _PolkitBackendAuthority ...@@ -62,7 +62,10 @@ struct _PolkitBackendAuthority
/** /**
* PolkitBackendAuthorityClass: * PolkitBackendAuthorityClass:
* @parent_class: The parent class. * @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 * @enumerate_actions: Enumerates registered actions on the
* system. See polkit_backend_authority_enumerate_actions() for * system. See polkit_backend_authority_enumerate_actions() for
* details. * details.
...@@ -100,7 +103,7 @@ struct _PolkitBackendAuthority ...@@ -100,7 +103,7 @@ struct _PolkitBackendAuthority
* the operation. See polkit_backend_authority_revoke_temporary_authorization_by_id() * the operation. See polkit_backend_authority_revoke_temporary_authorization_by_id()
* for details. * for details.
* *
* VFuncs that authority backends need to implement. * Class structure for #PolkitBackendAuthority.
*/ */
struct _PolkitBackendAuthorityClass struct _PolkitBackendAuthorityClass
{ {
......
...@@ -24,7 +24,7 @@ ...@@ -24,7 +24,7 @@
#include <polkit/polkit.h> #include <polkit/polkit.h>
#include "polkitbackendconfigsource.h" #include "polkitbackendconfigsource.h"
/** /* <internal>
* SECTION:polkitbackendconfigsource * SECTION:polkitbackendconfigsource
* @title: PolkitBackendConfigSource * @title: PolkitBackendConfigSource
* @short_description: Access configuration files * @short_description: Access configuration files
......
...@@ -1138,7 +1138,7 @@ check_authorization_sync (PolkitBackendAuthority *authority, ...@@ -1138,7 +1138,7 @@ check_authorization_sync (PolkitBackendAuthority *authority,
* *
* The default implementation returns a list with a single element for the super user. * 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(). * g_object_unref(), then free the list with g_list_free().
*/ */
GList * GList *
......
...@@ -25,7 +25,7 @@ ...@@ -25,7 +25,7 @@
#include <polkit/polkit.h> #include <polkit/polkit.h>
#include "polkitbackendlocalauthorizationstore.h" #include "polkitbackendlocalauthorizationstore.h"
/** /* <internal>
* SECTION:polkitbackendlocalauthorizationstore * SECTION:polkitbackendlocalauthorizationstore
* @title: PolkitBackendLocalAuthorizationStore * @title: PolkitBackendLocalAuthorizationStore
* @short_description: Watches a directory for authorization files * @short_description: Watches a directory for authorization files
......
...@@ -31,7 +31,7 @@ ...@@ -31,7 +31,7 @@
#define CKDB_PATH "/var/run/ConsoleKit/database" #define CKDB_PATH "/var/run/ConsoleKit/database"
/** /* <internal>
* SECTION:polkitbackendsessionmonitor * SECTION:polkitbackendsessionmonitor
* @title: PolkitBackendSessionMonitor * @title: PolkitBackendSessionMonitor
* @short_description: Monitor sessions * @short_description: Monitor sessions
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment