From 8d56599c05deb80c92ccbdbaa52f9996e53a9b57 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Sat, 31 Jan 2009 14:21:53 -0500 Subject: [PATCH] collapse request into a single signal and add docs for PolkitAgentSession --- 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(-) create mode 100644 src/polkitagent/polkitagentmarshal.list 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 @@ Authentication Agent API Reference - - + + 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 #include +#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) { -- 2.7.4