introduce a PolKitResult enumeration and make privilege files use that

doc/api/libpolkit/libpolkit-docs.xml

@@ -65,6 +65,8 @@
       </para>
     </partintro>
     <xi:include href="xml/libpolkit.xml"/>
+    <xi:include href="xml/libpolkit-error.xml"/>
+    <xi:include href="xml/libpolkit-result.xml"/>
     <xi:include href="xml/libpolkit-context.xml"/>
     <xi:include href="xml/libpolkit-privilege.xml"/>
     <xi:include href="xml/libpolkit-resource.xml"/>

libpolkit/Makefile.am

@@ -17,6 +17,8 @@ libpolkitincludedir=$(includedir)/PolicyKit/libpolkit
 
 libpolkitinclude_HEADERS =              		\
 	libpolkit.h					\
+	libpolkit-error.h				\
+	libpolkit-result.h				\
 	libpolkit-context.h				\
 	libpolkit-privilege.h				\
 	libpolkit-resource.h				\
@@ -27,6 +29,8 @@ libpolkitinclude_HEADERS =              		\
 
 libpolkit_la_SOURCES =                  	              		\
 	libpolkit.h			libpolkit.c			\
+	libpolkit-error.h		libpolkit-error.c		\
+	libpolkit-result.h		libpolkit-result.c		\
 	libpolkit-context.h		libpolkit-context.c		\
 	libpolkit-privilege.h		libpolkit-privilege.c		\
 	libpolkit-resource.h		libpolkit-resource.c		\

libpolkit/libpolkit-error.c

+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 8 -*- */
+/***************************************************************************
+ *
+ * libpolkit-error.c : GError error codes from PolicyKit
+ *
+ * Copyright (C) 2007 David Zeuthen, <david@fubar.dk>
+ *
+ * Licensed under the Academic Free License version 2.1
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307	 USA
+ *
+ **************************************************************************/
+
+/**
+ * SECTION:libpolkit-error
+ * @short_description: Error codes from PolicyKit.
+ *
+ * Error codes from PolicyKit.
+ **/
+
+#ifdef HAVE_CONFIG_H
+#  include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <pwd.h>
+#include <grp.h>
+#include <unistd.h>
+#include <errno.h>
+
+#include <glib.h>
+#include "libpolkit-error.h"
+
+
+/**
+ * libpolkit_error_quark:
+ * 
+ * Returns error domain for PolicyKit library.
+ * 
+ * Returns: The error domain
+ **/
+GQuark
+libpolkit_error_quark (void)
+{
+        return g_quark_from_static_string ("libpolkit-error-quark");
+}

libpolkit/libpolkit-error.h

+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 8 -*- */
+/***************************************************************************
+ *
+ * libpolkit-error.h : GError error codes from PolicyKit
+ *
+ * Copyright (C) 2007 David Zeuthen, <david@fubar.dk>
+ *
+ * Licensed under the Academic Free License version 2.1
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ **************************************************************************/
+
+#ifndef LIBPOLKIT_ERROR_H
+#define LIBPOLKIT_ERROR_H
+
+#include <glib.h>
+
+/**
+ * PolKitError:
+ * @POLKIT_ERROR_PRIVILEGE_FILE_INVALID_VALUE: There was an error parsing the given privilege file
+ *
+ * Error codes returned by PolicyKit
+ */
+typedef enum
+{      
+        POLKIT_ERROR_PRIVILEGE_FILE_INVALID_VALUE
+} PolKitError;
+
+/**
+ * POLKIT_ERROR:
+ *
+ * Error domain for PolicyKit library. Errors in this domain will be
+ * from the #PolKitError enumeration. See GError for details.
+ **/
+#define POLKIT_ERROR libpolkit_error_quark()
+
+GQuark libpolkit_error_quark (void);
+
+
+#endif /* LIBPOLKIT_RESULT_H */

libpolkit/libpolkit-privilege-file.c

@@ -37,7 +37,8 @@
 #include <errno.h>
 
 #include <glib.h>
-#include "libpolkit.h"
+#include "libpolkit-error.h"
+#include "libpolkit-result.h"
 #include "libpolkit-privilege-file.h"
 
 /**
@@ -47,16 +48,6 @@
  * This class is used to represent a privilege files.
  **/
 
-typedef enum
-{
-        LIBPOLKIT_RESULT_YES               = 1<<0,
-        LIBPOLKIT_RESULT_NO                = 1<<1,
-        LIBPOLKIT_RESULT_AUTH_REQ_ROOT     = 1<<2,
-        LIBPOLKIT_RESULT_AUTH_REQ_SELF     = 1<<3,
-        LIBPOLKIT_RESULT_AUTH_KEEP_SESSION = 1<<4,
-        LIBPOLKIT_RESULT_AUTH_KEEP_ALWAYS  = 1<<5
-} PolKitResult;
-
 /**
  * PolKitPrivilegeFile:
  *
@@ -81,34 +72,34 @@ parse_default (const char *key, char *s, PolKitResult* target, GError **error)
 {
         gboolean ret;
 
-        ret = TRUE;
-
-        if (strcmp (s, "yes") == 0) {
-                *target = LIBPOLKIT_RESULT_YES;
-        } else if (strcmp (s, "no") == 0) {
-                *target = LIBPOLKIT_RESULT_NO;
-        } else if (strcmp (s, "auth_root") == 0) {
-                *target = LIBPOLKIT_RESULT_NO | LIBPOLKIT_RESULT_AUTH_REQ_ROOT;
-        } else if (strcmp (s, "auth_root_keep_session") == 0) {
-                *target = LIBPOLKIT_RESULT_NO | LIBPOLKIT_RESULT_AUTH_REQ_ROOT | LIBPOLKIT_RESULT_AUTH_KEEP_SESSION;
-        } else if (strcmp (s, "auth_root_keep_always") == 0) {
-                *target = LIBPOLKIT_RESULT_NO | LIBPOLKIT_RESULT_AUTH_REQ_ROOT | LIBPOLKIT_RESULT_AUTH_KEEP_ALWAYS;
-        } else if (strcmp (s, "auth_self") == 0) {
-                *target = LIBPOLKIT_RESULT_NO | LIBPOLKIT_RESULT_AUTH_REQ_SELF;
-        } else if (strcmp (s, "auth_self_keep_session") == 0) {
-                *target = LIBPOLKIT_RESULT_NO | LIBPOLKIT_RESULT_AUTH_REQ_SELF | LIBPOLKIT_RESULT_AUTH_KEEP_SESSION;
-        } else if (strcmp (s, "auth_self_keep_always") == 0) {
-                *target = LIBPOLKIT_RESULT_NO | LIBPOLKIT_RESULT_AUTH_REQ_SELF | LIBPOLKIT_RESULT_AUTH_KEEP_ALWAYS;
-        } else {
+        ret = libpolkit_result_from_string_representation (s, target);
+        if (!ret) {
+                int n;
+                char *s2;
+                GString *str;
+
+                str = g_string_new (NULL);
+                for (n = 0; n < LIBPOLKIT_RESULT_N_RESULTS; n++) {
+                        if (n == LIBPOLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW)
+                                continue;
+
+                        if (str->len > 0) {
+                                g_string_append (str, ", ");
+                        }
+                        g_string_append (str, libpolkit_result_to_string_representation (n));
+                }
+                s2 = g_string_free (str, FALSE);
+
                 g_set_error (error, 
                              POLKIT_ERROR, 
                              POLKIT_ERROR_PRIVILEGE_FILE_INVALID_VALUE,
-                             "Value %s is not allowed for key %s - supported values are 'yes', 'no', 'auth_root', 'auth_root_keep_session', 'auth_root_keep_always', 'auth_self', 'auth_self_keep_session', 'auth_self_keep_always'", 
+                             "Value %s is not allowed for key %s - supported values are: %s", 
                              s, 
-                             key);
-                ret = FALSE;
+                             key,
+                             s2);
+                g_free (s2);
         }
-
+        
         g_free (s);
         return ret;
 }
@@ -183,7 +174,7 @@ error:
 
 /**
  * libpolkit_privilege_file_ref:
- * @privilege: the privilege object
+ * @privilege_file: the privilege file object
  * 
  * Increase reference count.
  * 
@@ -199,7 +190,7 @@ libpolkit_privilege_file_ref (PolKitPrivilegeFile *privilege_file)
 
 /**
  * libpolkit_privilege_file_unref:
- * @privilege: the privilege object
+ * @privilege_file: the privilege file object
  * 
  * Decreases the reference count of the object. If it becomes zero,
  * the object is freed. Before freeing, reference counts on embedded

libpolkit/libpolkit-result.c

+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 8 -*- */
+/***************************************************************************
+ *
+ * libpolkit-result.c : result codes from PolicyKit
+ *
+ * Copyright (C) 2007 David Zeuthen, <david@fubar.dk>
+ *
+ * Licensed under the Academic Free License version 2.1
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307	 USA
+ *
+ **************************************************************************/
+
+/**
+ * SECTION:libpolkit-result
+ * @short_description: Result of PolicyKit queries
+ *
+ * These functions are used to manipulate PolicyKit results.
+ **/
+
+#ifdef HAVE_CONFIG_H
+#  include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <pwd.h>
+#include <grp.h>
+#include <unistd.h>
+#include <errno.h>
+
+#include <glib.h>
+#include "libpolkit-result.h"
+
+
+static const struct {
+        PolKitResult result;
+        const char *str;
+} mapping[] = 
+{
+        {LIBPOLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW, "not_authorized"},
+        {LIBPOLKIT_RESULT_YES, "yes"},
+        {LIBPOLKIT_RESULT_NO, "no"},
+        {LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH, "auth_root"},
+        {LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH_KEEP_SESSION, "auth_root_keep_session"},
+        {LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH_KEEP_ALWAYS, "auth_root_keep_always"},
+        {LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH, "auth_self"},
+        {LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_SESSION, "auth_self_keep_session"},
+        {LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_ALWAYS, "auth_self_keep_always"},
+        {0, NULL}
+};
+
+
+/**
+ * libpolkit_result_to_string_representation:
+ * @result: the given result to get a textual representation of
+ * 
+ * Gives a textual representation of a #PolKitResult object.
+ * 
+ * Returns: string representing the result (do not free) or #NULL if the given result is invalid
+ **/
+const char *
+libpolkit_result_to_string_representation (PolKitResult result)
+{
+        if (result < 0 || result >= LIBPOLKIT_RESULT_N_RESULTS) {
+                g_warning ("The passed result code, %d, is not valid", result);
+                return NULL;
+        }
+
+        return mapping[result].str;
+}
+
+/**
+ * libpolkit_result_from_string_representation:
+ * @string: textual representation of a #PolKitResult object
+ * @out_result: return location for #PolKitResult
+ * 
+ * Given a textual representation of a #PolKitResult object, find the #PolKitResult value.
+ * 
+ * Returns: TRUE if the textual representation was valid, otherwise FALSE
+ **/
+gboolean
+libpolkit_result_from_string_representation (const char *string, PolKitResult *out_result)
+{
+        int n;
+
+        g_return_val_if_fail (out_result != NULL, FALSE);
+
+        for (n = 0; n < LIBPOLKIT_RESULT_N_RESULTS; n++) {
+                if (mapping[n].str == NULL)
+                        break;
+                if (strcmp (mapping[n].str, string) == 0) {
+                        *out_result = mapping[n].result;
+                        goto found;
+                }
+        }
+
+        /* don't print a warning; this is used by polkit-privilege-file-validate */
+        return FALSE;
+
+found:
+        return TRUE;
+
+}

libpolkit/libpolkit-result.h

+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 8 -*- */
+/***************************************************************************
+ *
+ * libpolkit-result.h : result codes from PolicyKit
+ *
+ * Copyright (C) 2007 David Zeuthen, <david@fubar.dk>
+ *
+ * Licensed under the Academic Free License version 2.1
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ **************************************************************************/
+
+#ifndef LIBPOLKIT_RESULT_H
+#define LIBPOLKIT_RESULT_H
+
+#include <glib.h>
+
+/**
+ * PolKitResult:
+ * @LIBPOLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW: The caller of libpolkit is not sufficiently privilege to know the answer.
+ * @LIBPOLKIT_RESULT_YES: Access granted.
+ * @LIBPOLKIT_RESULT_NO: Access denied.
+ * @LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH: Access denied, but authentication of the caller as 
+ * root will grant access to only that caller.
+ * @LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH_KEEP_SESSION: Access denied, but authentication of the caller as
+ * root will grant access for the remainder of the session the caller stems from.
+ * @LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH_KEEP_ALWAYS: Access denied, but authentication of the caller as
+ * root will grant access to the user of the caller in the future.
+ * @LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH: Access denied, but authentication of the caller as 
+ * his user will grant access to only that caller.
+ * @LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_SESSION: Access denied, but authentication of the caller as
+ * his user will grant access for the remainder of the session the caller stems from.
+ * @LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_ALWAYS: Access denied, but authentication of the caller as
+ * his user will grant access to the user of the caller in the future.
+ * @LIBPOLKIT_RESULT_N_RESULTS: Number of result codes
+ *
+ * Result codes from queries to PolicyKit.
+ */
+typedef enum
+{
+        LIBPOLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW,
+        LIBPOLKIT_RESULT_YES,
+        LIBPOLKIT_RESULT_NO,
+        LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH,
+        LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH_KEEP_SESSION,
+        LIBPOLKIT_RESULT_ONLY_VIA_ROOT_AUTH_KEEP_ALWAYS,
+        LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH,
+        LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_SESSION,
+        LIBPOLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_ALWAYS,
+        LIBPOLKIT_RESULT_N_RESULTS
+} PolKitResult;
+
+const char *
+libpolkit_result_to_string_representation (PolKitResult result);
+
+gboolean
+libpolkit_result_from_string_representation (const char *string, PolKitResult *out_result);
+
+#endif /* LIBPOLKIT_RESULT_H */

libpolkit/libpolkit.c

@@ -61,12 +61,20 @@
  * Typically, this information is used to e.g. bootstrap the system
  * insofar that it can be used to start login greeters on the given
  * video hardware (e.g. resources) on the given user-configured seats.
+ *
+ * If a resource is not associated with any seat, it is assumed to be
+ * available to any local seat.
+ *
+ * Returns: A #PolKitResult - can only be one of
+ * #LIBPOLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW or
+ * #LIBPOLKIT_RESULT_YES (if the callback was invoked)
  */
-void
+PolKitResult
 libpolkit_get_seat_resource_association (PolKitContext       *pk_context,
                                          PolKitSeatVisitorCB  visitor,
                                          gpointer            *user_data)
 {
+        return LIBPOLKIT_RESULT_YES;
 }
 
 /**
@@ -79,15 +87,16 @@ libpolkit_get_seat_resource_association (PolKitContext       *pk_context,
  * same comments noted in libpolkit_get_seat_resource_association() about the
  * source purely being user configuration applies here as well.
  *
- * Returns: TRUE if, and only if, the given resource is
- * associated with the given seat.
+ * Returns: A #PolKitResult - can only be one of
+ * #LIBPOLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW,
+ * #LIBPOLKIT_RESULT_YES, #LIBPOLKIT_RESULT_NO.
  */
-gboolean
+PolKitResult
 libpolkit_is_resource_associated_with_seat (PolKitContext   *pk_context,
                                             PolKitResource  *resource,
                                             PolKitSeat      *seat)
 {
-        return FALSE;
+        return LIBPOLKIT_RESULT_NO;
 }
 
 /**
@@ -99,16 +108,17 @@ libpolkit_is_resource_associated_with_seat (PolKitContext   *pk_context,
  *
  * Determine if a given session can access a given resource in a given way.
  *
- * Returns: TRUE if, and only if, the given session can access the
- * given resource in the given way.
+ * Returns: A #PolKitResult - can only be one of
+ * #LIBPOLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW,
+ * #LIBPOLKIT_RESULT_YES, #LIBPOLKIT_RESULT_NO.
  */
-gboolean
+PolKitResult
 libpolkit_can_session_access_resource (PolKitContext   *pk_context,
                                        PolKitPrivilege *privilege,
                                        PolKitResource  *resource,
                                        PolKitSession   *session)
 {
-        return FALSE;
+        return LIBPOLKIT_RESULT_NO;
 }
 
 /**
@@ -120,20 +130,14 @@ libpolkit_can_session_access_resource (PolKitContext   *pk_context,
  *
  * Determine if a given caller can access a given resource in a given way.
  *
- * Returns: TRUE if, and only if, the given caller can access the
- * given resource in the given way.
+ * Returns: A #PolKitResult specifying if, and how, the caller can
+ * access the resource in the given way
  */
-gboolean
+PolKitResult
 libpolkit_can_caller_access_resource (PolKitContext   *pk_context,
                                       PolKitPrivilege *privilege,
                                       PolKitResource  *resource,
                                       PolKitCaller    *caller)
 {
-        return FALSE;
-}
-
-GQuark
-libpolkit_error_quark (void)
-{
-        return g_quark_from_static_string ("libpolkit-error-quark");
+        return LIBPOLKIT_RESULT_NO;
 }

libpolkit/libpolkit.h

@@ -31,6 +31,8 @@
 #include <sys/types.h>
 #include <glib.h>
 
+#include <libpolkit/libpolkit-error.h>
+#include <libpolkit/libpolkit-result.h>
 #include <libpolkit/libpolkit-context.h>
 #include <libpolkit/libpolkit-privilege.h>
 #include <libpolkit/libpolkit-resource.h>
@@ -38,8 +40,6 @@
 #include <libpolkit/libpolkit-session.h>
 #include <libpolkit/libpolkit-caller.h>
 
-
-
 /**
  * PolKitSeatVisitorCB:
  * @seat: the seat
@@ -47,43 +47,33 @@
  * @user_data: user data
  *
  * Visitor function for libpolkit_get_seat_resource_association(). The caller should _not_ unref the passed objects.
- *
  */
 typedef void (*PolKitSeatVisitorCB) (PolKitSeat      *seat,
                                      PolKitResource **resources_associated_with_seat,
                                      gpointer         user_data);
 
-void
+PolKitResult
 libpolkit_get_seat_resource_association (PolKitContext       *pk_context,
                                          PolKitSeatVisitorCB  visitor,
                                          gpointer            *user_data);
 
-gboolean
+PolKitResult
 libpolkit_is_resource_associated_with_seat (PolKitContext   *pk_context,
                                             PolKitResource  *resource,
                                             PolKitSeat      *seat);
 
-gboolean
+PolKitResult
 libpolkit_can_session_access_resource (PolKitContext   *pk_context,
                                        PolKitPrivilege *privilege,
                                        PolKitResource  *resource,
                                        PolKitSession   *session);
 
-gboolean
+PolKitResult
 libpolkit_can_caller_access_resource (PolKitContext   *pk_context,
                                       PolKitPrivilege *privilege,
                                       PolKitResource  *resource,
                                       PolKitCaller    *caller);
 
-typedef enum
-{
-        POLKIT_ERROR_PRIVILEGE_FILE_INVALID_VALUE
-} PolKitError;
-
-#define POLKIT_ERROR libpolkit_error_quark()
-
-GQuark libpolkit_error_quark (void);
-
 #endif /* LIBPOLKIT_H */