PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Sat Jan 31 11:24:09 PST 2009
docs/polkit/polkit-docs.xml | 4
src/polkitagent/Makefile.am | 12 ++
src/polkitagent/polkitagentmarshal.list | 1
src/polkitagent/polkitagentsession.c | 135 ++++++++++++++++++++------------
4 files changed, 103 insertions(+), 49 deletions(-)
New commits:
commit 8d56599c05deb80c92ccbdbaa52f9996e53a9b57
Author: David Zeuthen <davidz at redhat.com>
Date: Sat Jan 31 14:21:53 2009 -0500
collapse request into a single signal and add docs for PolkitAgentSession
diff --git a/docs/polkit/polkit-docs.xml b/docs/polkit/polkit-docs.xml
index e37b9ab..ed8361e 100644
--- a/docs/polkit/polkit-docs.xml
+++ b/docs/polkit/polkit-docs.xml
@@ -89,8 +89,8 @@
<reference id="ref-authentication-agent-api">
<title>Authentication Agent API Reference</title>
- <xi:include href="../polkitagent/xml/polkitagentauthenticationagent.xml"/>
- <xi:include href="../polkitagent/xml/polkitagentauthenticationsession.xml"/>
+ <xi:include href="../polkitagent/xml/polkitagentlistener.xml"/>
+ <xi:include href="../polkitagent/xml/polkitagentsession.xml"/>
</reference>
<reference id="manpages">
diff --git a/src/polkitagent/Makefile.am b/src/polkitagent/Makefile.am
index 7d0d857..49f6afd 100644
--- a/src/polkitagent/Makefile.am
+++ b/src/polkitagent/Makefile.am
@@ -30,6 +30,16 @@ $(BUILT_SOURCES) : Makefile.am $(top_srcdir)/data/org.freedesktop.PolicyKit1.Aut
--introspection-xml $(top_srcdir)/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml \
$(NULL)
+BUILT_SOURCES += \
+ polkitagentmarshal.h polkitagentmarshal.c \
+ $(NULL)
+
+polkitagentmarshal.h : polkitagentmarshal.list
+ glib-genmarshal --prefix=polkit_agent_marshal $(srcdir)/polkitagentmarshal.list --header > $@.tmp && mv $@.tmp $@
+
+polkitagentmarshal.c: polkitagentmarshal.h polkitagentmarshal.list
+ (echo "#include \"polkitagentmarshal.h\""; glib-genmarshal --prefix=polkit_agent_marshal $(srcdir)/polkitagentmarshal.list --body) > $@.tmp && mv $@.tmp $@
+
lib_LTLIBRARIES=libpolkit-agent-1.la
libpolkit_agent_1includedir=$(includedir)/polkit-1/polkitagent
@@ -78,5 +88,7 @@ install-exec-hook:
CLEANFILES = $(BUILT_SOURCES)
+EXTRA_DIST = polkitagentmarshal.list
+
clean-local :
rm -f *~
diff --git a/src/polkitagent/polkitagentmarshal.list b/src/polkitagent/polkitagentmarshal.list
new file mode 100644
index 0000000..c4effb6
--- /dev/null
+++ b/src/polkitagent/polkitagentmarshal.list
@@ -0,0 +1 @@
+VOID:STRING,BOOLEAN
diff --git a/src/polkitagent/polkitagentsession.c b/src/polkitagent/polkitagentsession.c
index fef2119..18b5b12 100644
--- a/src/polkitagent/polkitagentsession.c
+++ b/src/polkitagent/polkitagentsession.c
@@ -22,9 +22,30 @@
/**
* SECTION:polkitagentsession
* @title: PolkitAgentSession
- * @short_description: Authentcation Sessions
+ * @short_description: Authentication Session
*
- * The #PolkitAgentSession class is used for interacting with an authentication system.
+ * The #PolkitAgentSession class is an abstraction used for interacting with the
+ * native authentication system (for example PAM) for obtaining authorizations.
+ * This class is typically used together with instances that are derived from
+ * the #PolkitAgentListener abstract base class.
+ *
+ * To perform the actual authentication, #PolkitAgentSession uses a trusted suid helper.
+ * The authentication conversation is done through a pipe. This is transparent; the user
+ * only need to handle the
+ * #PolkitAgentSession::request,
+ * #PolkitAgentSession::show-info,
+ * #PolkitAgentSession::show-error and
+ * #PolkitAgentSession::completed
+ * signals and invoke polkit_agent_session_response() in response to requests.
+ *
+ * If the user successfully authenticates, the authentication helper will invoke
+ * a method on the PolicyKit daemon (see polkit_authority_authentication_agent_response_sync())
+ * with the given @cookie. Upon receiving a positive response from the PolicyKit daemon (via
+ * the authentication helper), the #PolkitAgentSession::completed signal will be emitted
+ * with the @gained_authorization paramter set to %TRUE.
+ *
+ * If the user is unable to authenticate, the #PolkitAgentSession::completed signal will
+ * be emitted with the @gained_authorization paramter set to %FALSE.
*/
#include "config.h"
@@ -35,6 +56,7 @@
#include <sys/wait.h>
#include <pwd.h>
+#include "polkitagentmarshal.h"
#include "polkitagentsession.h"
struct _PolkitAgentSession
@@ -64,8 +86,7 @@ struct _PolkitAgentSessionClass
enum
{
- REQUEST_ECHO_ON_SIGNAL,
- REQUEST_ECHO_OFF_SIGNAL,
+ REQUEST_SIGNAL,
SHOW_INFO_SIGNAL,
SHOW_ERROR_SIGNAL,
COMPLETED_SIGNAL,
@@ -111,49 +132,27 @@ polkit_agent_session_class_init (PolkitAgentSessionClass *klass)
gobject_class->finalize = polkit_agent_session_finalize;
/**
- * PolkitAgentSession::request-echo-on:
+ * PolkitAgentSession::request:
* @session: A #PolkitAgentSession.
- * @request: The request to show the user, e.g. "name: "
+ * @request: The request to show the user, e.g. "name: " or "password: ".
+ * @echo_on: %TRUE if the response to the request SHOULD be echoed on the
+ * screen, %FALSE if the response MUST NOT be echoed to the screen.
*
- * Emitted when the user is requested to answer a question. User input
- * should be echoed on the screen in the clear.
+ * Emitted when the user is requested to answer a question.
*
- * When the response has been collected from the user, call
- * polkit_agent_session_response().
+ * When the response has been collected from the user, call polkit_agent_session_response().
*/
- signals[REQUEST_ECHO_ON_SIGNAL] = g_signal_new ("request-echo-on",
- POLKIT_AGENT_TYPE_SESSION,
- G_SIGNAL_RUN_LAST,
- 0, /* class offset */
- NULL, /* accumulator */
- NULL, /* accumulator data */
- g_cclosure_marshal_VOID__STRING,
- G_TYPE_NONE,
- 1,
- G_TYPE_STRING);
-
- /**
- * PolkitAgentSession::request-echo-off:
- * @session: A #PolkitAgentSession.
- * @request: The request to show the user, e.g. "password: "
- *
- * Emitted when the user is requested to answer a question. User input
- * MUST NOT be echoed on the screen in the clear.
- *
- * When the response has been collected from the user, call
- * polkit_agent_session_response().
- */
- signals[REQUEST_ECHO_OFF_SIGNAL] = g_signal_new ("request-echo-off",
- POLKIT_AGENT_TYPE_SESSION,
- G_SIGNAL_RUN_LAST,
- 0, /* class offset */
- NULL, /* accumulator */
- NULL, /* accumulator data */
- g_cclosure_marshal_VOID__STRING,
- G_TYPE_NONE,
- 1,
- G_TYPE_STRING);
-
+ signals[REQUEST_SIGNAL] = g_signal_new ("request",
+ POLKIT_AGENT_TYPE_SESSION,
+ G_SIGNAL_RUN_LAST,
+ 0, /* class offset */
+ NULL, /* accumulator */
+ NULL, /* accumulator data */
+ polkit_agent_marshal_VOID__STRING_BOOLEAN,
+ G_TYPE_NONE,
+ 2,
+ G_TYPE_STRING,
+ G_TYPE_BOOLEAN);
/**
* PolkitAgentSession::show-info:
@@ -194,10 +193,13 @@ polkit_agent_session_class_init (PolkitAgentSessionClass *klass)
/**
* PolkitAgentSession::completed:
* @session: A #PolkitAgentSession.
- * @authentication_result: %TRUE only if the user sucessfully authenticated.
+ * @gained_authorization: %TRUE only if the authorization was successfully obtained.
*
* Emitted when the authentication session has been completed or
- * cancelled. The user should unref @session.
+ * cancelled. The @gained_authorization parameter is %TRUE only if
+ * the user successfully authenticated.
+ *
+ * Upon receiving this signal, the user should free @session using g_object_unref().
*/
signals[COMPLETED_SIGNAL] = g_signal_new ("completed",
POLKIT_AGENT_TYPE_SESSION,
@@ -211,6 +213,22 @@ polkit_agent_session_class_init (PolkitAgentSessionClass *klass)
G_TYPE_BOOLEAN);
}
+/**
+ * polkit_agent_session_new:
+ * @identity: The identity to authenticate.
+ * @cookie: The cookie obtained from the PolicyKit daemon
+ *
+ * Creates a new authentication session.
+ *
+ * The caller should connect to the
+ * #PolkitAgentSession::request,
+ * #PolkitAgentSession::show-info,
+ * #PolkitAgentSession::show-error and
+ * #PolkitAgentSession::completed
+ * signals and then call polkit_agent_session_initiate() to initiate the authentication session.
+ *
+ * Returns: A #PolkitAgentSession. Free with g_object_unref().
+ **/
PolkitAgentSession *
polkit_agent_session_new (PolkitIdentity *identity,
const gchar *cookie)
@@ -326,11 +344,11 @@ io_watch_have_data (GIOChannel *channel,
if (g_str_has_prefix (line, "PAM_PROMPT_ECHO_OFF "))
{
- g_signal_emit_by_name (session, "request-echo-off", line + sizeof "PAM_PROMPT_ECHO_OFF " - 1);
+ g_signal_emit_by_name (session, "request", line + sizeof "PAM_PROMPT_ECHO_OFF " - 1, FALSE);
}
else if (g_str_has_prefix (line, "PAM_PROMPT_ECHO_ON "))
{
- g_signal_emit_by_name (session, "request-echo-on", line + sizeof "PAM_PROMPT_ECHO_ON " - 1);
+ g_signal_emit_by_name (session, "request", line + sizeof "PAM_PROMPT_ECHO_ON " - 1, TRUE);
}
else if (g_str_has_prefix (line, "PAM_ERROR_MSG "))
{
@@ -366,6 +384,14 @@ io_watch_have_data (GIOChannel *channel,
return TRUE;
}
+/**
+ * polkit_agent_session_response:
+ * @session: A #PolkitAgentSession.
+ * @response: Response from the user, typically a password.
+ *
+ * Function for providing response to requests received
+ * via the #PolkitAgentSession::request signal.
+ **/
void
polkit_agent_session_response (PolkitAgentSession *session,
const gchar *response)
@@ -385,6 +411,14 @@ polkit_agent_session_response (PolkitAgentSession *session,
write (session->child_stdin, newline, 1);
}
+/**
+ * polkit_agent_session_initiate:
+ * @session: A #PolkitAgentSession.
+ *
+ * Initiates the authentication session.
+ *
+ * Use polkit_agent_session_cancel() to cancel the session.
+ **/
void
polkit_agent_session_initiate (PolkitAgentSession *session)
{
@@ -454,6 +488,13 @@ error:
}
+/**
+ * polkit_agent_session_cancel:
+ * @session: A #PolkitAgentSession.
+ *
+ * Cancels an authentication session. This will make @session emit the #PolkitAgentSession::completed
+ * signal.
+ **/
void
polkit_agent_session_cancel (PolkitAgentSession *session)
{
More information about the hal-commit
mailing list