Commit d8e6d66b authored by David Zeuthen's avatar David Zeuthen

Various doc cleanups

Signed-off-by: 's avatarDavid Zeuthen <davidz@redhat.com>
parent 536765bc
......@@ -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"/>.
......
......@@ -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
......
This diff is collapsed.
......@@ -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
......
......@@ -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);
......
......@@ -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.
*/
......
......@@ -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.
**/
......
......@@ -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
......
......@@ -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,
......
......@@ -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.
**/
......
......@@ -30,7 +30,7 @@
#include "polkitbackendactionpool.h"
/**
/* <internal>
* SECTION:polkitbackendactionpool
* @title: PolkitBackendActionPool
* @short_description: Registered actions
......
......@@ -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
{
......
......@@ -24,7 +24,7 @@
#include <polkit/polkit.h>
#include "polkitbackendconfigsource.h"
/**
/* <internal>
* SECTION:polkitbackendconfigsource
* @title: PolkitBackendConfigSource
* @short_description: Access configuration files
......
......@@ -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 *
......
......@@ -25,7 +25,7 @@
#include <polkit/polkit.h>
#include "polkitbackendlocalauthorizationstore.h"
/**
/* <internal>
* SECTION:polkitbackendlocalauthorizationstore
* @title: PolkitBackendLocalAuthorizationStore
* @short_description: Watches a directory for authorization files
......
......@@ -31,7 +31,7 @@
#define CKDB_PATH "/var/run/ConsoleKit/database"
/**
/* <internal>
* SECTION:polkitbackendsessionmonitor
* @title: PolkitBackendSessionMonitor
* @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