PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Sat Jan 31 12:42:50 PST 2009
docs/polkitagent/Makefile.am | 1
docs/polkitagent/polkitagent-sections.txt | 34 ++++++++++
src/polkitagent/polkitagentlistener.c | 99 ++++++++++++++++++++++++------
src/polkitagent/polkitagentlistener.h | 26 ++++++-
src/polkitagent/polkitagentsession.c | 7 ++
5 files changed, 143 insertions(+), 24 deletions(-)
New commits:
commit da781b2e933f95f8c7d7eaa9f9df74e841494351
Author: David Zeuthen <davidz at redhat.com>
Date: Sat Jan 31 15:41:05 2009 -0500
add docs for PolkitAgentListener
diff --git a/docs/polkitagent/Makefile.am b/docs/polkitagent/Makefile.am
index 248aa35..75a134a 100644
--- a/docs/polkitagent/Makefile.am
+++ b/docs/polkitagent/Makefile.am
@@ -81,7 +81,6 @@ CLEANFILES += *~ \
polkitagent-overrides.txt \
polkitagent-undeclared.txt \
polkitagent-undocumented.txt \
- polkitagent-sections.txt \
*.stamp \
-rf html xml \
$(NULL)
diff --git a/docs/polkitagent/polkitagent-sections.txt b/docs/polkitagent/polkitagent-sections.txt
new file mode 100644
index 0000000..38c1de6
--- /dev/null
+++ b/docs/polkitagent/polkitagent-sections.txt
@@ -0,0 +1,34 @@
+<SECTION>
+<FILE>polkitagentsession</FILE>
+PolkitAgentSession
+polkit_agent_session_new
+polkit_agent_session_initiate
+polkit_agent_session_response
+polkit_agent_session_cancel
+<SUBSECTION Standard>
+POLKIT_AGENT_SESSION
+POLKIT_AGENT_IS_SESSION
+POLKIT_AGENT_TYPE_SESSION
+polkit_agent_session_get_type
+POLKIT_AGENT_SESSION_CLASS
+POLKIT_AGENT_IS_SESSION_CLASS
+POLKIT_AGENT_SESSION_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>polkitagentlistener</FILE>
+<TITLE>PolkitAgentListener</TITLE>
+PolkitAgentListener
+PolkitAgentListenerClass
+polkit_agent_listener_initiate_authentication
+polkit_agent_listener_initiate_authentication_finish
+polkit_agent_register_listener
+<SUBSECTION Standard>
+POLKIT_AGENT_LISTENER
+POLKIT_AGENT_IS_LISTENER
+POLKIT_AGENT_TYPE_LISTENER
+polkit_agent_listener_get_type
+POLKIT_AGENT_LISTENER_CLASS
+POLKIT_AGENT_IS_LISTENER_CLASS
+POLKIT_AGENT_LISTENER_GET_CLASS
+</SECTION>
diff --git a/src/polkitagent/polkitagentlistener.c b/src/polkitagent/polkitagentlistener.c
index 05042aa..15be7db 100644
--- a/src/polkitagent/polkitagentlistener.c
+++ b/src/polkitagent/polkitagentlistener.c
@@ -29,12 +29,22 @@
/**
* SECTION:polkitagentlistener
* @title: PolkitAgentListener
- * @short_description: Authentication Agent Listener
+ * @short_description: Abstract base class for Authentication Agents
*
- * The #PolkitAgentListener is an abstract base class used for implementing authentication agents.
+ * The #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.
+ *
+ * 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().
*/
-/* private class for exporting an interface D-Bus */
+/* private class for exporting a D-Bus interface */
#define TYPE_SERVER (server_get_type ())
#define SERVER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), TYPE_SERVER, Server))
@@ -229,35 +239,58 @@ listener_died (gpointer user_data,
g_object_unref (server);
}
-void
-polkit_agent_export_listener (PolkitAgentListener *listener,
- const gchar *session_id,
- const gchar *object_path)
+/**
+ * polkit_agent_register_listener:
+ * @listener: An instance of a class that is derived from #PolkitAgentListener.
+ * @session_id: The session id to become an authentication agent for or %NULL for the current session.
+ * @object_path: The D-Bus object path to use for the authentication agent or %NULL for the default object path.
+ * @error: Return location for error.
+ *
+ * Registers @listener with the PolicyKit daemon as an authentication agent for @session_id. This
+ * is implemented by registering a D-Bus object at @object_path on the unique name assigned by the
+ * system message bus.
+ *
+ * Whenever the PolicyKit daemon needs to authenticate the user of @session_id for an action, the methods
+ * polkit_agent_listener_initiate_authentication() and polkit_agent_listener_initiate_authentication_finish()
+ * will be invoked on @listener.
+ *
+ * Note that registration of an authentication agent can fail; for example another authentication agent may
+ * already be registered.
+ *
+ * To unregister @listener, simply free it with g_object_unref().
+ *
+ * Returns: %TRUE if @listener has been registered, %FALSE if @error is set.
+ **/
+gboolean
+polkit_agent_register_listener (PolkitAgentListener *listener,
+ const gchar *session_id,
+ const gchar *object_path,
+ GError **error)
{
Server *server;
- GError *error;
server = SERVER (g_object_new (TYPE_SERVER, NULL));
server->session_id = g_strdup (session_id);
- server->object_path = g_strdup (object_path);
+ server->object_path = object_path != NULL ? g_strdup (object_path) :
+ g_strdup ("/org/freedesktop/PolicyKit1/AuthenticationAgent");
server->listener = listener;
- /* take a weak ref and kill server when listener dies */
- g_object_weak_ref (G_OBJECT (server->listener), listener_died, server);
-
egg_dbus_connection_register_interface (server->system_bus,
server->object_path,
_POLKIT_AGENT_TYPE_AUTHENTICATION_AGENT,
G_OBJECT (server),
G_TYPE_INVALID);
- error = NULL;
- if (!server_register (server, &error))
+ if (!server_register (server, error))
{
- g_printerr ("Failed to register as an authentication agent: %s\n", error->message);
- g_printerr ("Will attempt to register when the PolicyKit daemon is back up\n");
- g_error_free (error);
+ g_object_unref (server);
+ return FALSE;
}
+
+ /* take a weak ref and kill server when listener dies */
+ g_object_weak_ref (G_OBJECT (server->listener), listener_died, server);
+
+ return TRUE;
}
typedef struct
@@ -409,6 +442,27 @@ polkit_agent_listener_class_init (PolkitAgentListenerClass *klass)
{
}
+/**
+ * polkit_agent_listener_initiate_authentication:
+ * @listener: A #PolkitAgentListener.
+ * @action_id: The action to authenticate for.
+ * @cookie: The cookie for the authentication request.
+ * @identities: A list of #PolkitIdentity objects that the user can choose to authenticate as.
+ * @cancellable: A #GCancellable.
+ * @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.
+ *
+ * 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.
+ **/
void
polkit_agent_listener_initiate_authentication (PolkitAgentListener *listener,
const gchar *action_id,
@@ -427,6 +481,17 @@ polkit_agent_listener_initiate_authentication (PolkitAgentListener *listener,
user_data);
}
+/**
+ * polkit_agent_listener_initiate_authentication_finish:
+ * @listener: A #PolkitAgentListener.
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to polkit_agent_listener_initiate_authentication().
+ * @error: Return location for error.
+ *
+ * Finishes an authentication request from the PolicyKit daemon, see
+ * polkit_agent_listener_initiate_authentication() for details.
+ *
+ * Returns: %TRUE if @error is set.
+ **/
gboolean
polkit_agent_listener_initiate_authentication_finish (PolkitAgentListener *listener,
GAsyncResult *res,
diff --git a/src/polkitagent/polkitagentlistener.h b/src/polkitagent/polkitagentlistener.h
index d71acf7..fae6c96 100644
--- a/src/polkitagent/polkitagentlistener.h
+++ b/src/polkitagent/polkitagentlistener.h
@@ -37,19 +37,32 @@ G_BEGIN_DECLS
#if 0
typedef struct _PolkitAgentListener PolkitAgentListener;
#endif
-typedef struct _PolkitAgentListenerClass PolkitAgentListenerClass;
+typedef struct _PolkitAgentListenerClass PolkitAgentListenerClass;
+/**
+ * PolkitAgentListener:
+ *
+ * The #PolkitAgentListener struct should not be accessed directly.
+ */
struct _PolkitAgentListener
{
GObject parent_instance;
};
+/**
+ * PolkitAgentListenerClass:
+ * @parent_class: The parent class.
+ * @initiate_authentication: Handle an authentication request, see polkit_agent_listener_initiate_authentication().
+ * @initiate_authentication_finish: Finishes handling an authentication request, see polkit_agent_listener_initiate_authentication_finish().
+ *
+ * VFuncs that authentication agents needs to implement.
+ */
struct _PolkitAgentListenerClass
{
+ /*< public >*/
GObjectClass parent_class;
- /*< public >*/
- /* VFuncs */
+ /* Vtable */
void (*initiate_authentication) (PolkitAgentListener *listener,
const gchar *action_id,
const gchar *cookie,
@@ -86,9 +99,10 @@ gboolean polkit_agent_listener_initiate_authentication_finish (PolkitAgentList
GAsyncResult *res,
GError **error);
-void polkit_agent_export_listener (PolkitAgentListener *listener,
- const gchar *session_id,
- const gchar *object_path);
+gboolean polkit_agent_register_listener (PolkitAgentListener *listener,
+ const gchar *session_id,
+ const gchar *object_path,
+ GError **error);
G_END_DECLS
diff --git a/src/polkitagent/polkitagentsession.c b/src/polkitagent/polkitagentsession.c
index 18b5b12..184dd2b 100644
--- a/src/polkitagent/polkitagentsession.c
+++ b/src/polkitagent/polkitagentsession.c
@@ -59,8 +59,15 @@
#include "polkitagentmarshal.h"
#include "polkitagentsession.h"
+/**
+ * PolkitAgentSession:
+ *
+ * The #PolkitAgentSession struct should not be accessed directly.
+ */
struct _PolkitAgentSession
{
+ /*< private >*/
+
GObject parent_instance;
gchar *cookie;
More information about the hal-commit
mailing list